<div align="center">
# 🧠 RepoMemory
**Turn coding-agent sessions into portable, repo-aware memory.**
[![npm version](https://img.shields.io/npm/v/repomemory?style=for-the-badge)](https://npmjs.com/package/repomemory)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue?style=for-the-badge)](./LICENSE)
[![Stars](https://img.shields.io/github/stars/Lay4U/repomemory?style=for-the-badge)](https://github.com/Lay4U/repomemory/stargazers)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue?style=for-the-badge&logo=typescript)](https://www.typescriptlang.org/)
[![MCP](https://img.shields.io/badge/MCP-Compatible-green?style=for-the-badge)](https://modelcontextprotocol.io)
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
```bash
# 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
```
```bash
# 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
```bash
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
```mermaid
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
```bash
npm install
npm run typecheck
npm test
npm run build
```
Node.js 20+ required.

## Contributing
Contributions are welcome.
Please read [CONTRIBUTING.md](./CONTRIBUTING.md) before opening a PR.

## License
MIT © 2026 Lay4U. See [LICENSE](./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.