repomemory

The Problem

Every time you open a project with Claude Code, Cursor, Copilot, or any AI coding agent:

• It re-discovers your architecture from scratch
• It proposes changes that were already debated and rejected
• It re-introduces bugs that were already fixed

Your `CLAUDE.md` / `.cursorrules` helps, but it's static and gets stale.

The Solution

.context/
├── index.md              ← Quick orientation (loaded every session)
├── facts/                ← Architecture, database, deployment
├── decisions/            ← "We chose Drizzle over Prisma because..."
├── regressions/          ← "This broke before. Here's what happened."
├── preferences/          ← Your coding style — follows you across all repos
├── sessions/             ← Auto-captured AI session summaries
└── changelog/            ← Monthly git history syncs

Facts tell agents how things work. Decisions prevent re-debating. Regressions prevent re-breaking. Preferences teach agents how you code.

Quick Start

With an API key (Claude Code, terminal workflows)

npx repomemory go

One command: sets up global profile, creates `.context/`, configures Claude Code + Cursor, runs AI analysis, prints CLAUDE.md instructions.

With Cursor (no API key needed)

npx repomemory setup cursor

This installs everything Cursor needs:

• MCP server in `~/.cursor/mcp.json` (auto-starts repomemory in every project)
• Rules in `.cursor/rules/repomemory.mdc` (teaches Cursor's AI to use context)
• 6 commands in `.cursor/commands/` (run with `/` in Cursor chat)

Then in Cursor chat, type:

/repomemory-analyze

Cursor's own AI scans your repo and populates `.context/` via the MCP tools. No external API key required — your Cursor subscription handles it.

Available Cursor commands:

Guided wizard

npx repomemory wizard

Walks through provider selection, tool integration, and first analysis. If no API keys are detected, offers a "None — I use Cursor" option that skips external analysis entirely.

Non-interactive (CI-safe)

npx repomemory go --yes --provider anthropic --embedding-provider gemini --max-files 80

No prompts when `--yes` / `--defaults` / `--no-prompt` is used.

MCP Server — Agents With Real Memory

The real power is the MCP server. When configured via `repomemory setup claude`, it auto-starts with Claude Code and gives agents 7 tools:

Agent: "Let me orient myself in this project..."
→ context_auto_orient()
→ Returns: project overview, preferences, recent sessions, recent changes

Agent: "Let me search for context about the auth flow..."
→ context_search("authentication flow")
→ Auto-routes to facts/ category, returns compact results

Agent: "I found a race condition. Let me record this."
→ context_write(category="regressions", filename="token-refresh-race", content="...")
→ Persisted. Detects if it supersedes an existing entry.

Sessions are auto-captured on shutdown. Zero config — `repomemory setup claude` handles everything.

Supported Tools

> Cursor users: You don't need any API key. Run `npx repomemory setup cursor`, then use `/repomemory-analyze` in Cursor chat. Cursor's AI does the analysis using the MCP tools — whatever model Cursor is using (it can even switch models mid-task).

Supported Providers

Embeddings (optional, for semantic search): Gemini `text-embedding-004` (free, default) or OpenAI `text-embedding-3-small`. Auto-detected from available API keys.

All Commands

repomemory go                            # One-command setup (add --yes for non-interactive)
repomemory wizard                        # Interactive guided setup
repomemory analyze                       # AI-powered repo analysis
repomemory analyze --merge               # Update without overwriting edits
repomemory analyze --dry-run             # Preview without API call
repomemory search                 # Search knowledge base from terminal
repomemory status                        # Coverage and freshness report
repomemory doctor                        # Diagnostics and health check
repomemory dashboard                     # Local web UI (localhost:3333)
repomemory risk                          # Hotspots, coupling, ownership analysis
repomemory risk -f src/auth.ts           # Targeted risk assessment for specific files
repomemory sync                          # Sync git history to changelog
repomemory setup                   # Configure Claude/Cursor/Copilot/etc
repomemory hook install                  # Auto-sync changelog on commits
repomemory global list                   # Manage global developer context
repomemory global export                 # Export global context as JSON

Configuration

`.repomemory.json` in your repo root (all fields optional):

{
  "provider": "anthropic",
  "model": "claude-sonnet-4-6",
  "embeddingProvider": "gemini",
  "hybridAlpha": 0.5,
  "maxFilesForAnalysis": 80,
  "enableGlobalContext": true
}

Custom `ignorePatterns` and `keyFilePatterns` are additive — they extend built-in defaults, not replace them.

Why Not Just CLAUDE.md?

repomemory doesn't replace `CLAUDE.md` — it complements it. `CLAUDE.md` is for instructions and rules. `.context/` holds the knowledge that grows over time.

Contributing

See CONTRIBUTING.md for development setup, testing, and contribution guidelines.

License

MIT