repo-memory
> Shared, git-tracked working memory for AI agents that share a codebase.
> What one Claude / Cursor / Cline learns about your repo, the next one
> picks up automatically. No database. No SaaS. Just files in your repo.
The problem
Every AI session that touches your repo starts from zero. It re-greps the
same files. It re-discovers the same conventions. It re-asks the same
questions you already answered three sessions ago. Multi-user / multi-tool
makes it worse: your teammate's Cursor and your Claude Code learn the same
codebase independently.
There is CLAUDE.md / .cursorrules for rules the human writes. But
there is nothing for facts an agent verified — "the auth middleware
lives at src/auth/middleware.py:42", "PR #387 chose httpx over requests
because of HTTP/2", "don't run migrations during peak hours".
repo-memory is that nothing. A .ai-memory/ directory you commit to
your repo. Every AI tool reads from it, writes to it. Git is the database.
Layout```
your-repo/
├── .ai-memory/
│ ├── README.md # explains the convention
│ ├── facts.jsonl # append-only structured facts with evidence
│ ├── decisions/ # one markdown per non-trivial decision
│ │ └── 2026-05-19-pick-httpx.md
│ └── gotchas.md # one-line "watch out for X" notes
├── src/
└── README.md
Pure files. Sync over git. No daemon, no DB, no auth. Works offline.
---
## Install```bash
pip install repo-memory-mcp
# or
uvx repo-memory-mcp --help
Python ≥3.10. Depends only on the official mcp SDK (for the MCP server).
Quick start```bash
cd your-repo
repo-memory init # creates .ai-memory/ + adds CLAUDE.md hint
repo-memory add-fact "Auth middleware lives in src/auth/middleware.py" \
--file src/auth/middleware.py --lines 42-180 --tool grep
repo-memory add-decision "Use httpx not requests" \
--body "HTTP/2 + async support; we already use anyio."
repo-memory add-gotcha "Don't run migrations during 9-11am UTC peak"
repo-memory show # render everything as Markdown
repo-memory list-facts --tag auth
Then commit `.ai-memory/` like any other file:```bash
git add .ai-memory/
git commit -m "memory: record auth middleware location + httpx decision"
git push
Anyone else (human or AI) who pulls the repo now sees those facts/decisions
immediately.
LLM & AI Agent Readable Specification
> For agents discovering this repo through search or MCP indexing.
Identity
- name:
repo-memory - purpose: read/write a structured, git-tracked memory store about the
current codebase so multiple AI agents (and humans) don't re-learn it. - transport: CLI (
repo-memory) and MCP stdio (repo-memory-mcp). - storage: plain files under
.ai-memory/in the repo. Sync = git.
When to call which tool
| Tool | When |
|---|---|
get_repo_memory |
At the start of any task on this repo. |
add_fact |
After you verify a non-obvious fact (location, behavior, convention). Include evidence so the next agent can re-verify cheaply. |
add_decision |
After a non-trivial choice (architecture, library, trade-off). Body should explain why, not just what. |
add_gotcha |
After a surprise that wasted your time. |
list_facts |
When you want only facts in a specific area (tag, source_file). |
Recommended agent workflow```
- agent.call("get_repo_memory") -> absorb prior context
- ...do task, run tools, verify things...
- agent.call("add_fact", claim, evidence) -> for each new fact
- agent.call("add_decision", title, body) -> if a choice was made
- session ends, human commits .ai-memory/ -> shared via git
### MCP server install
Add to your client config (Claude Desktop / Cursor / Cline):```json
{
"mcpServers": {
"repo-memory": {
"command": "uvx",
"args": ["repo-memory-mcp", "--repo", "/abs/path/to/the/repo"]
}
}
}
Or set REPO_MEMORY_ROOT env var instead of --repo.
Exposes 5 tools: get_repo_memory, add_fact, list_facts,
add_decision, add_gotcha.
Why git, not a database
- Zero infra. No service to host, no account to create, no API key
to rotate. - Already authoritative. Git history is the single source of truth.
git blametells you which agent added which fact and when. - Works offline. Plane, train, conference WiFi — all fine.
- PR review. Suspicious or wrong facts get filtered through normal
code review. - Per-repo scope. A fact about repo A doesn't leak into repo B; the
store is local to the repo.
Schema (for tooling authors)
facts.jsonl — one JSON object per line:json
{
"id": "abc123def456",
"ts": "2026-05-19T18:00:00Z",
"claim": "Auth middleware lives in src/auth/middleware.py",
"evidence": {
"file": "src/auth/middleware.py",
"lines": "42-180",
"tool": "grep",
"command": "rg 'def authenticate' src/",
"verified_at": "2026-05-19T18:00:00Z"
},
"tags": ["auth"],
"added_by": "claude-opus-4.7"
}
Append-only. Stale entries stay. Readers consult verified_at and
re-verify if they want.
Automatic discovery hint
repo-memory init also appends a short discoverability section to your
repo's CLAUDE.md (or AGENTS.md if you already have one) telling any
AI agent that enters the repo to check .ai-memory/ first and to record
new findings back into it. Idempotent — re-running won't duplicate.
Opt out with --no-claude-md.
The appended block is delimited by and, so you can hand-edit other parts of your
CLAUDE.md freely.
CLI reference
| Command | Effect |
|---|---|
repo-memory init [--no-claude-md] |
Create .ai-memory/ skeleton + (default) update CLAUDE.md/AGENTS.md. |
repo-memory show [--limit N] |
Print everything as one Markdown doc. |
repo-memory add-fact "" [--file F --lines L --tool T --command C --tag T --by AGENT] |
Append a fact. |
repo-memory list-facts [--tag T] [--source-file F] [--since ISO] [--limit N] [--json] |
List/filter facts. |
repo-memory add-decision "" [--body MD] |
Write a decision file. |
repo-memory list-decisions |
List decision file paths. |
repo-memory add-gotcha "" |
Append a one-line gotcha. |
All commands take --root PATH if your CWD isn't the repo root.
About the author
Built by yubinkim444, who also makes
Kay's Records — an app for iOS
and Android.
If this project saved you time, giving the app a try is the nicest way to say
thanks.
License
MIT © yubinkim444
