Repomemory

## Stop repeating the same mistakes across agent sessions RepoMemory is a repo-aware memory layer + MCP server for coding agents. It captures what happened in one session and reuses it in the next. When context persists, momentum persists. ## The Problem AI coding agents don't share memory by default. Each session starts from scratch. Known failures and rationale disappear. The same mistakes get repeated. ## The Solution RepoMemory records failures, diffs, decisions, and file relationships. It stores this in a local memory graph and serves it to any MCP client. The next agent starts informed, not blind. ### Before RepoMemory - Claude fails - Codex starts fresh - Codex repeats the same error

After RepoMemory

• Claude fails
• RepoMemory captures why
• Codex recalls context
• Codex succeeds

Demo

# Claude's session: refactoring fails
repomemory capture git-diff --agent claude
repomemory capture test --output "..." --status fail --agent claude
repomemory capture decision --message "Auth middleware needs JWT validation" --agent claude

# Switch to Codex: full context automatically
repomemory recall src/middleware/auth.ts
# → Recent failures: JWT validation missing in auth middleware
# → Decision: needs JWT validation before route handlers
# → Related files: src/routes/api.ts, src/config/jwt.ts

# Daily usage
repomemory init
repomemory capture git-diff --agent codex --files src/middleware/auth.ts
repomemory search "jwt validation" --file src/middleware/auth.ts

Features

• 🧠 Repo-aware memory graph backed by SQLite
• 🔁 Cross-agent continuity (Claude, Codex, Cursor, OpenHands)
• 🧩 MCP server for in-session memory retrieval
• 📂 File-level recall with related-file discovery
• 🧪 Failure-aware capture from tests and terminal logs
• 🌿 Git-aware capture of diff and commit history
• ⚡ Fast local-first search and recall
• 📦 Portable exports (json or sqlite)

Quick Start

npm i -g repomemory
repomemory init
repomemory serve

Alternative (no global install):

npx repomemory init
npx repomemory capture git-diff --agent codex
npx repomemory recall src/index.ts

MCP Integration

Use RepoMemory from any MCP client:

{
  "mcpServers": {
    "repomemory": {
      "command": "npx",
      "args": ["repomemory", "serve"]
    }
  }
}

Compatible with:

• Cursor
• Claude Desktop
• VS Code
• Any MCP-compatible client

Available MCP Tools

Tool	What it does	Typical prompt
search_memory	Search memory entries by query/filter	"Find recent JWT auth failures"
why_changed	Explain rationale behind file changes	"Why was middleware order changed?"
recent_failures	List recent failed attempts	"What already failed in this area?"
recall_context	Return consolidated file context	"Load context before I edit"
related_files	Find files changed together	"What neighboring files matter here?"
remember	Write a memory entry	"Save this decision"
get_stats	Show memory activity and volume	"How much memory is captured?"

How It Works

graph TB
  A[Agent Session] --> B[Capture]
  B --> C[Memory Graph - SQLite]
  C --> D[MCP Server]
  D --> E[Next Agent Session]
  B --> B1[git diff/commit]
  B --> B2[test results]
  B --> B3[terminal logs]
  B --> B4[PR reviews]
  B --> B5[decisions]

Operational flow:

1. Capture signals from active coding sessions.
2. Normalize into structured memory entries.
3. Persist entries and file relations in SQLite.
4. Expose retrieval through CLI and MCP tools.
5. Reuse context in the next agent session.

CLI Reference

repomemory init

Initializes .repomemory/ and local SQLite database. Usage:

repomemory init
repomemory init --force

Notes:

• Run once per repository.
• --force recreates storage.

repomemory capture <type>

Captures a memory entry for a source event.

Supported capture types:

• git-diff
• git-commit
• terminal
• test
• decision

Common options:

• --agent <name>
• --message <text>
• --files <paths...>
• --tags <tags...>

Examples:

repomemory capture git-diff --agent claude
repomemory capture decision --message "Validate JWT before route handlers" --files src/middleware/auth.ts
repomemory capture terminal --message "vitest auth suite failing" --tags failure auth
repomemory capture git-commit --agent codex --tags release

repomemory search <query>

Searches memory entries.

Filters:

• --type <type>
• --agent <agent>
• --file <path>
• --limit <n> (default: 20)
• --since <date> (ISO-8601)

Examples:

repomemory search "jwt" --file src/middleware/auth.ts --agent codex --limit 10
repomemory search "failing snapshot" --type test --since 2026-01-01
repomemory search "rate limit" --agent claude

repomemory recall <file>

Recalls context for a target file.

Options:

• --depth <n> (default: 10)
• --format <text|json> (default: text)

Examples:

repomemory recall src/middleware/auth.ts
repomemory recall src/middleware/auth.ts --depth 15
repomemory recall src/middleware/auth.ts --format json

Typical output includes:

• Recent failures
• Related decisions
• File relationships
• Session breadcrumbs

repomemory serve

Starts the MCP server.

Options:

• --transport <stdio|sse> (default: stdio)
• --port <n> for SSE mode (default: 3000)

Examples:

repomemory serve
repomemory serve --transport sse --port 4317

repomemory export

Exports captured memory.

Options:

• --format <json|sqlite> (default: json)
• --output <path>

Examples:

repomemory export --format json --output ./repomemory-export.json
repomemory export --format sqlite --output ./repomemory-export.db

repomemory stats

Shows repository memory stats.

Usage:

repomemory stats

Architecture

RepoMemory uses a local-first, layered design.

Capture Layer

Captures and structures:

• Git diffs/commits
• Test outcomes
• Terminal commands
• PR/issue review context
• Engineering decisions

Memory Layer

Persists normalized records in SQLite tables:

• entries
• entry_files
• sessions
• file_relations

Retrieval Layer

Supports:

• Full-text search
• File-centric recall
• Recent failure discovery
• Decision/rationale lookup
• Related-file traversal

MCP Layer

Exposes memory operations as MCP tools for agent workflows.

Use Cases

• Multi-agent handoffs in a single repository
• Long-running refactors over multiple sessions
• Preventing repeated test failures after context switches
• Preserving review rationale after merges
• Building an auditable memory trail for AI-assisted engineering

Why RepoMemory

• Reduces repeated mistakes across sessions
• Speeds up agent handoffs
• Improves consistency of engineering decisions
• Keeps context local and portable

Development

npm install
npm run typecheck
npm test
npm run build

Node.js 20+ required.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening a PR.

License

MIT © 2026 Lay4U. See LICENSE.

Star CTA

If RepoMemory helped you avoid repeated failures across sessions, star the project. It helps more teams discover practical, persistent memory for coding agents. Stop repeating the same mistakes across agent sessions.