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

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

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