npx repomemory go

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 re-reads the same files to understand patterns
• 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 manually maintained. It gets stale.

The Solution

repomemory creates a structured, searchable knowledge base that AI agents can search, read, and write to during sessions:

.context/
├── index.md              <- Quick orientation (loaded every session)
├── facts/
│   ├── architecture.md   <- Services, how they connect, deploy targets
│   ├── database.md       <- Schema overview, key tables, relationships
│   └── deployment.md     <- How to deploy, env vars, CI/CD
├── decisions/
│   ├── why-drizzle.md    <- "We chose Drizzle because X, not Prisma because Y"
│   └── auth-strategy.md  <- "JWT over sessions because Z"
├── regressions/
│   ├── sql-join-bug.md   <- "This broke before. Here's what happened."
│   └── token-refresh.md  <- "53-day cycle, don't touch without reading this"
├── preferences/          <- How YOU code (new in v1.1)
│   ├── coding-style.md   <- "Prefer functional components, TypeScript strict"
│   └── patterns.md       <- "Always use barrel exports, no default exports"
├── sessions/             <- AI session summaries (auto-captured on shutdown)
└── 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

One-Command Setup (v1.1)

npx repomemory go

This single command:

1. Creates .context/ if it doesn't exist
2. Configures Claude Code MCP server if installed
3. Runs AI analysis if context is empty
4. Prints CLAUDE.md instructions to copy-paste

Interactive Setup

npx repomemory wizard

The wizard walks you through provider selection, tool integration, and first analysis — all in one beautiful flow.

Manual Setup

# 1. Initialize
npx repomemory init

# 2. Set your API key
export ANTHROPIC_API_KEY=sk-ant-...    # or OPENAI_API_KEY, GEMINI_API_KEY, GROK_API_KEY

# 3. Analyze your repo (2-5 min, uses AI)
npx repomemory analyze

# 4. Connect to your AI tool
npx repomemory setup claude     # Claude Code (MCP server auto-starts)
npx repomemory setup cursor     # Cursor
npx repomemory setup copilot    # GitHub Copilot
npx repomemory setup windsurf   # Windsurf
npx repomemory setup cline      # Cline
npx repomemory setup aider      # Aider
npx repomemory setup continue   # Continue

# 5. Commit to git — your team shares the knowledge
git add .context/ && git commit -m "Add repomemory knowledge base"

Features

MCP Server — AI Agents With Memory

The real power is the MCP server. It gives AI agents 6 tools to search, orient, read, write, and delete context:

npx repomemory serve

When configured via repomemory setup claude, the MCP server auto-starts with Claude Code:

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

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

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

What's New in v1.1

Hybrid Search — Keyword search (FTS5) + optional vector/semantic search via OpenAI or Gemini embeddings. Falls back to keyword-only when no embedding API key is available. Configure with embeddingProvider in .repomemory.json.

Intelligent Category Routing — Search queries are auto-routed to the most relevant category. "Why did we use X" routes to decisions/. "Bug in login" routes to regressions/. "Coding style" routes to preferences/. If no results found, retries across all categories.

Auto-Session Capture — The MCP server tracks all tool calls during a session and auto-writes a summary to sessions/ when the server shuts down. Works with ALL MCP clients (Claude Code, Cursor, Copilot, Windsurf) — no hooks required.

Progressive Disclosure — Search returns compact one-line summaries by default (~50 tokens per result). Use detail="full" for longer snippets. Reduces context window usage by ~10x.

Auto-Purge Detection — When writing a new entry, the server checks for existing entries on the same topic and warns about potential supersedes. Use the supersedes parameter to auto-delete the old entry.

Preferences Category — New preferences/ category for coding style, preferred patterns, tool configs, and formatting rules. Personal developer knowledge that persists across sessions.

One-Command Setup — npx repomemory go replaces the 4-step init + analyze + setup + copy flow.

Dashboard Improvements — Edit entries inline, server-side FTS5 search, real-time polling, JSON export, proper markdown rendering.

Web Dashboard

Browse, search, and edit your context files in a beautiful local web UI:

npx repomemory dashboard

Opens http://localhost:3333 with:

• Category filtering and server-side full-text search
• Inline editing with save
• Real-time polling for changes
• JSON export
• Proper markdown rendering

Smart Analysis

# Full analysis
npx repomemory analyze

# Preview what would happen (no API call)
npx repomemory analyze --dry-run

# Update without overwriting your manual edits
npx repomemory analyze --merge

# Use a different provider or model
npx repomemory analyze --provider openai --model gpt-4o

Features:

• Cost estimation before running
• API key validation before expensive calls
• Retry with exponential backoff on failures
• Coverage report showing facts/decisions/regressions
• Merge mode that preserves manual edits

Git Sync

npx repomemory sync

Syncs recent git commits to changelog/YYYY-MM.md with smart deduplication.

Status & Coverage

npx repomemory status

Shows coverage bars, freshness indicators, stale file warnings, and suggestions.

Supported Providers

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

Supported AI Tools

All Commands

Configuration

Create .repomemory.json in your repo root:

{
  "provider": "anthropic",
  "model": "claude-sonnet-4-6",
  "contextDir": ".context",
  "maxFilesForAnalysis": 80,
  "maxGitCommits": 100,
  "ignorePatterns": [],
  "keyFilePatterns": [],
  "embeddingProvider": "openai",
  "hybridAlpha": 0.5
}

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

Embedding config (optional):

• embeddingProvider: "openai" or "gemini" — which API to use for embeddings
• embeddingModel: Override the default embedding model
• embeddingApiKey: Explicit API key for embeddings (falls back to env vars)
• hybridAlpha: Weight between keyword (1.0) and semantic (0.0) search. Default: 0.5

How It Works

Initial Analysis

1. Scans your repo — files, directories, languages, frameworks
2. Reads key files — package.json, configs, schemas, READMEs, CLAUDE.md
3. Mines git history — commits, contributors, change patterns
4. Respects .gitignore — won't scan ignored files
5. Sends everything to your AI model with a structured analysis prompt
6. Writes organized knowledge to .context/
7. Indexes all files for FTS5 full-text search + optional embeddings

During Sessions (MCP Server)

• Agent orients itself with context_auto_orient at session start
• Agent searches for relevant context with intelligent category routing
• Agent writes discoveries, decisions, and preferences during work
• Auto-purge detection warns about superseded entries
• Session activity is auto-captured on server shutdown
• Knowledge accumulates session over session
• Next session starts with everything previous sessions learned

Why Not Just Use CLAUDE.md?

repomemory doesn't replace CLAUDE.md — it complements it. Your CLAUDE.md stays 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