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

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

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:

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

1. agent.call("get_repo_memory")            -> absorb prior context
2. ...do task, run tools, verify things...
3. agent.call("add_fact", claim, evidence)  -> for each new fact
4. agent.call("add_decision", title, body)  -> if a choice was made
5. session ends, human commits .ai-memory/   -> shared via git

MCP server install

Add to your client config (Claude Desktop / Cursor / Cline):

{
  "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 blame tells 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:

{
  "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 <!-- BEGIN: repo-memory --> and <!-- END: repo-memory -->, 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 "<claim>" [--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 "<title>" [--body MD]	Write a decision file.
repo-memory list-decisions	List decision file paths.
repo-memory add-gotcha "<note>"	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