repomemory

<div align="center">

🧠 RepoMemory

Turn coding-agent sessions into portable, repo-aware memory.      Claude broke the build. Codex picks it up. RepoMemory makes sure it doesn't repeat the same mistake. </div>

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): ``bash npx repomemory init npx repomemory capture git-diff --agent codex npx repomemory recall src/index.ts ``

MCP Integration

Use RepoMemory from any MCP client: ``json { "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: ``bash 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: ``bash 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: ``bash 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: ``bash 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: ``bash repomemory serve repomemory serve --transport sse --port 4317 ``

repomemory export

Exports captured memory.

Options:

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

Examples: ``bash repomemory export --format json --output ./repomemory-export.json repomemory export --format sqlite --output ./repomemory-export.db ``

repomemory stats

Shows repository memory stats.

Usage: ``bash 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.