yubinkim444/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
Pure files. Sync over git. No daemon, no DB, no auth. Works offline.
---
Install
Python ≥3.10. Depends only on the official mcp SDK (for the MCP server).
---
Quick start
Then commit .ai-memory/ like any other file:
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
MCP server install
Add to your client config (Claude Desktop / Cursor / Cline):
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.