devmemory 0.1.5

Sync AI coding context from Git AI to Redis Agent Memory Server for semantic search and recall.

DevMemory 🚀🧠

TL;DR: DevMemory is a long‑term memory for your AI coding agents.
It remembers why code was written, how it changed, and what your team learned — then feeds that back into your agents. No more “reinvent the bug” speedruns. 🐛🔥

Built on Git AI for silent capture and Redis Agent Memory Server for semantic search and recall.

---

💡 What DevMemory Does (in human terms)

• 🪝 Hooks into your git workflow via Git AI notes
• 🧬 Extracts rich memories:
  • Commit summaries (who, what, why, which agent/model, how much AI)
  • Per‑file code snippets
  • Prompt‑level context with acceptance metrics
• 🧠 Stores everything in Redis AMS as semantic vectors
• 🔍 Lets you ask:
  “How do we handle auth?” → it searches, then LLM‑synthesizes an actual answer with sources
• 🧾 Ships a knowledge protocol: .devmemory/knowledge/*.md + CLI + Cursor rules so humans and agents keep the docs alive together

If Entire saves how agents worked and Git AI tracks who wrote which line, DevMemory is the part that answers “Okay, but what did we actually learn?”.

---

🧮 How It Works

Developer commits code
        │
        ▼
Git AI captures AI attribution, prompts, agent/model info
        │
        ▼
DevMemory syncs enriched memories to Redis AMS (automatic via post-commit hook)
        │
        ├─► Semantic search via CLI (with LLM-synthesized answers)
        ├─► MCP recall in Cursor IDE (agents search memory before coding)
        └─► Context briefing auto-generated on branch switch

The knowledge loop:

1. Capture – Git AI silently records AI code attribution, prompts, and agent/model info on every commit
2. Enrich – DevMemory extracts three layers per commit: enriched summary, per‑file code snapshots, and prompt‑level context with acceptance metrics
3. Search – Semantic vector search with LLM‑powered answer synthesis (RAG over your git history)
4. Recall – Cursor agents read memory via MCP before writing code, and persist new decisions after
5. Learn – Human‑curated knowledge files (.devmemory/knowledge/*.md) feed the same store, capturing architecture decisions and gotchas

🧵 Think of it as git log + “what we should have written in the ADR” + your AI agents actually reading it.

---

🎥 Demo (what it feels like)

Imagine:

devmemory status                    # ✅ Stack + hooks look good
git commit -am "feat: add user auth"   # You used an AI agent heavily

# Normally the post-commit hook runs this for you in the background:
#   (sleep 2 && devmemory sync --latest 2>/dev/null) &
# but you can also trigger it manually:
devmemory sync --latest
devmemory search "how do we handle auth in this service?"

You get:

• A concise answer synthesized by the LLM (RAG), describing:
  • Which files implement auth
  • Which agent/model was used
  • Key decisions (e.g., why JWT vs sessions)
• A Sources table listing:
  • Commit summaries
  • Relevant per‑file code snippets
  • The original prompts that drove the changes

Sample search result:

$ devmemory search "why we use redis memory server instead of other databases?"

Searching for: why we use redis memory server instead of other databases?
Synthesizing answer...

╭────────────────────────────────────────────────────────────── Answer ───────────────────────────────────────────────────────────────╮
│                                                                                                                                     │
│  Short answer: because Redis Agent Memory Server (AMS) already provides the exact semantic-memory features we need (embeddings,     │
│  topic extraction, NER, deduplication) while being battle‑tested infra, so it reduces operational complexity and keeps the CLI      │
│  lightweight.                                                                                                                       │
│                                                                                                                                     │
│  Details / evidence from the repo:                                                                                                  │
│                                                                                                                                     │
│   • AMS handles embeddings, topic extraction and NER internally and provides built‑in memory deduplication (see                     │
│     .devmemory/knowledge/architecture.md, commit b0abbb04ad13).                                                                     │
│   • The same AMS image serves both REST (port 8000) and MCP (port 9050) endpoints used by the CLI (see docker-compose.yml and       │
│     ams_client.py; feature enable commit f025d01e107c).                                                                             │
│   • README and ams_client.py show we store semantic vectors in Redis AMS and call its /v1/long-term-memory APIs, avoiding the need  │
│     to run a separate vector DB (README.md commit 2b7602a5318a and devmemory/core/ams_client.py).                                   │
│                                                                                                                                     │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Sources (10 relevant, 20 filtered out)

 #    Score    Type        Source                                                                      
 1    0.302    semantic    Why Redis Agent Memory Server                                               
 2    0.614    semantic    Memory Types and Their Purpose                                              
 3    0.613    semantic    feat: enable devmemory CLI with redis AMS and git-ai (f025d01e107c)         
 4    0.641    semantic    feat: add more metadata from the session to the memory (4ccf7529bd4e)       
 5    0.671    semantic    fix: use the --quite to show the one line update (139d559bdaa0)             
 6    0.677    semantic    Fix: terminal hang issue and the correct saved memories coun (daf56666f1f1) 
 7    0.512    episodic    .devmemory/knowledge/architecture.md (b0abbb04ad13)                         
 8    0.550    episodic    devmemory/core/ams_client.py (f025d01e107c)                                 
 9    0.588    episodic    README.md (2b7602a5318a)                                                    
 10   0.561    episodic    docker-compose.yml (f025d01e107c)                    

Auto-sync example:

---

🚀 Quick Start

Prerequisites

• Git
• Docker + Docker Compose
• Python 3.10+
• OpenAI API key (for embeddings and answer synthesis)
• Git AI (for AI code attribution capture)

One‑Line Setup

bash scripts/install.sh

This script:

• Checks Docker / Python / Git AI and verifies the Docker daemon is running
• Installs uv if not present, then installs the devmemory CLI via uv tool install
• Sets up .env from .env.example
• Starts Redis + AMS + MCP via Docker
• Configures git hooks + Cursor MCP + agent rules in the current repo

Manual Setup

git clone https://github.com/devmemory/devmemory
cd devmemory

# Set up environment
cp .env.example .env
# Edit .env and add your OPENAI_API_KEY

# Start the stack
make up

# Install the CLI (requires uv: https://docs.astral.sh/uv/)
uv tool install --editable .

# Set up hooks, MCP config, and Cursor rules in your project
cd /path/to/your/project
devmemory install

# Check everything works
devmemory status

---

⌨️ CLI Commands

Core workflow 🧠

devmemory sync                       # Sync unsynced Git AI commits to Redis
devmemory sync --latest              # Sync only the latest commit
devmemory sync --all                 # Re-sync all commits
devmemory sync --dry-run             # Preview what would be synced
devmemory search "how do we auth"    # Semantic search with LLM-synthesized answer
devmemory search "auth" -n 5         # Limit results
devmemory search "auth" --raw        # Raw results without LLM synthesis
devmemory status                     # Show system health, sync state, hooks

Code archaeology 🔍

devmemory why src/auth.py            # Explain why a file exists and how it evolved
devmemory why src/auth.py login      # Focus on a specific function or class
devmemory why src/auth.py --raw      # Show raw memories and git history without synthesis

Knowledge management 📚

devmemory add "We chose Redis over Postgres for vector search because..." --topic architecture
devmemory add --interactive          # Interactive mode with prompts
devmemory learn                      # Sync .devmemory/knowledge/*.md into memory store
devmemory learn --dry-run            # Preview what would be synced
devmemory context                    # Generate .devmemory/CONTEXT.md from git state + memory

Setup and config ⚙️

devmemory install                    # Set up git hooks + Cursor MCP + agent rules
devmemory install --skip-hook        # Skip hook installation
devmemory install --skip-rule        # Skip Cursor agent rules
devmemory config show                # Show current config
devmemory config set endpoint URL    # Change AMS endpoint
devmemory config reset               # Reset to defaults

---

📚 Knowledge Files

DevMemory supports human‑curated knowledge in .devmemory/knowledge/*.md.
Each markdown section (## heading) becomes a separate searchable memory.

.devmemory/
├── CONTEXT.md              # Auto-generated context briefing (gitignored)
└── knowledge/
    ├── architecture.md     # Architecture decisions and rationale
    ├── gotchas.md          # Known issues and workarounds
    └── conventions.md      # Coding patterns and project rules

Knowledge files use frontmatter for metadata:

---
topics: [architecture, decisions]
entities: [Redis, AMS]
---

## Why We Chose Redis

We chose Redis with vector search over dedicated vector DBs
because it's already part of our stack and reduces complexity.

Run devmemory learn to sync knowledge files into the memory store.
Both automated capture (Git AI) and human knowledge feed the same searchable store.

🧠 Pro tip: Treat .devmemory/knowledge/ like living ADRs. Small, focused, and updated often.

---

🤝 Cursor Agent Integration

devmemory install sets up three things for Cursor:

1. MCP server config (~/.cursor/mcp.json) – Agents can search and write to the memory store via MCP tools (search_long_term_memory, create_long_term_memories, etc.)
2. Agent behavior rules (.cursor/rules/devmemory.mdc) – Instructs agents to search memory before coding, persist decisions after significant work, and maintain knowledge files
3. Context rule (.cursor/rules/devmemory-context.mdc) – Agents read .devmemory/CONTEXT.md at task start for a pre‑built briefing

The result is a compounding loop: each agent session makes the next one smarter.
Your AI stops acting like a goldfish and starts acting like a teammate. 🐠➡️🧑‍💻

---

🪝 Git Hooks

DevMemory installs two git hooks:

Hook	What it does
post-commit	Runs devmemory sync --latest in background (auto‑syncs after every commit)
post-checkout	Runs devmemory context --quiet (refreshes context briefing on branch switch)

---

🏗 Architecture

┌─────────────────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Developer Machine         │     │  Docker Stack     │     │  Cursor IDE     │
│                             │     │                   │     │                 │
│  Git AI (git hooks)         │     │  Redis Stack      │     │  MCP Client     │
│         │                   │     │    ▲              │     │       │         │
│         ▼                   │     │    │              │     │       ▼         │
│  Git Notes (refs/ai)        │     │  AMS API (:8000)  │     │  MCP Server     │
│         │                   │     │    ▲              │     │  (:9050)        │
│         ▼                   │     │    │              │     │                 │
│  devmemory sync ────────────┼─────┼────┘              │     │                 │
│                             │     │                   │     │                 │
│  devmemory search ──────────┼─────┼────► AMS Search ──┼─────┼──► LLM synth    │
│                             │     │                   │     │                 │
│  .devmemory/knowledge/*.md  │     │                   │     │  Agent rules    │
│         │                   │     │                   │     │  (.cursor/rules)│
│  devmemory learn ───────────┼─────┼────┘              │     │                 │
│                             │     │                   │     │                 │
│  devmemory context ─────────┼─────┼────► .devmemory/CONTEXT.md              │
└─────────────────────────────┘     └──────────────────┘     └─────────────────┘

---

🧾 What Gets Captured

DevMemory extracts three memory layers from each Git AI commit:

Layer	Type	What it contains	Answers
Commit summary	semantic	Agent/model, prompts used, AI contribution stats, acceptance metrics, technologies, files	“Which agent was used?”, “How much AI code?”
Per-file code	episodic	Code snippets from diffs with key lines (imports, class/function defs)	“How do we call the API?”, “What client for Redis?”
Prompt context	semantic	Actual prompt text, acceptance rate, affected files	“What prompts were used?”, “What was the developer asking?”

Unique data points captured via Git AI and surfaced by DevMemory:

• AI vs human lines per commit
• Acceptance rate (lines accepted unchanged vs overridden)
• Time waiting for AI per commit
• Agent and model used (Cursor, Copilot, Claude Code, etc.)

---

🐳 Docker Stack

The docker-compose.yml runs:

Service	Port	Description
redis	6379	Redis Stack (vector search, JSON, streams)
api	8000	Agent Memory Server REST API
mcp	9050	MCP server for Cursor IDE (SSE mode)
redis-insight	16381	RedisInsight UI (debug profile only)

make up       # Start stack
make down     # Stop stack
make logs     # View logs
make debug    # Start with RedisInsight
make clean    # Stop and remove volumes
make verify   # Run verification checks

---

🌍 How DevMemory Fits the Ecosystem

Tool	What it does	Data store
Git AI	Captures AI code attribution and prompts	Git Notes + SQLite
Entire	Captures agent sessions/checkpoints	Git branch
DevMemory	Turns captured data into searchable, evolving team knowledge	Redis AMS

Git AI and Entire are capture tools.
DevMemory is a memory and knowledge tool — it makes captured data searchable via semantic vector search, synthesizes answers with LLM, and feeds context back to AI agents automatically.

---

⚙️ Configuration

Config is stored in ~/.devmemory/config.json:

{
  "ams_endpoint": "http://localhost:8000",
  "mcp_endpoint": "http://localhost:9050",
  "namespace": "default",
  "user_id": ""
}

Environment variables (in .env):

Variable	Default	Description
OPENAI_API_KEY	(required)	Used for embeddings and answer synthesis
GENERATION_MODEL	gpt-5-mini	Model for LLM answer synthesis
EMBEDDING_MODEL	text-embedding-3-small	Model for vector embeddings

---

🧑‍💻 Contributing

Contributions, bug reports, and wild feature ideas are very welcome. 💌
See CONTRIBUTING.md for details on running the stack, tests, and linting.

If you build something cool with DevMemory, please open an issue or PR and show it off. ✨

---

⭐️ Supporting the Project

If DevMemory helps you or your team:

• Star the repo on GitHub ⭐
• Tell your AI‑obsessed friends
• Open issues with real‑world workflows you’d like memory support for

Happy shipping — and may your agents never forget another architecture decision again. 🧠📦🚀