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

npx repomemory go

This single command:

1. Sets up your global developer profile (~/.repomemory/global/) — your preferences follow you everywhere
2. Creates .context/ if it doesn't exist
3. Configures Claude Code MCP server if installed
4. Runs AI analysis if context is empty
5. 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.4

CLI Search — Search your knowledge base from the terminal. Invaluable for debugging "why doesn't the agent know X?"

repomemory search "authentication"
repomemory search "why drizzle" --category decisions --detail full

Post-Commit Context Hook — repomemory setup claude now installs a Claude Code hook that fires after git commits, reminding the agent to record what it learned using context_write. This is the biggest gap in agent memory — they commit code but don't write down what they discovered. The hook fixes that automatically.

Embedding Provider in Setup — The wizard now asks which embedding provider you want for semantic search (auto-detects available API keys). The go and init commands accept --embedding-provider so you're not stuck with hidden defaults in .repomemory.json.

Smarter Session Capture — Sessions are now captured when anything was written OR 3+ tool calls were made. Previously required both 3+ calls AND 60+ seconds, which silently lost short productive sessions.

Staleness Warnings — context_auto_orient now flags entries untouched for 30+ days so agents know which context might be outdated.

What's New in v1.2

Global Developer Context — Your coding preferences now follow you across all repos. A global context store at ~/.repomemory/global/ is auto-created on first run. The preferences/ category defaults to global scope — write once, available everywhere. Repo-level preferences override global when needed.

Scope Routing — All MCP tools gain an optional scope parameter ("repo" or "global"). Defaults are automatic: preferences go global, everything else stays repo-local. Search merges results from both stores with repo-first dedup.

CLI: repomemory global — New subcommand to manage global context directly: list, read, write, delete, export, import. Export/import enables backup and machine migration.

Unicode Filename Handling — Accented characters are now transliterated (café → cafe) instead of stripped to hyphens. NFKD normalization preserves readable filenames.

Search Improvements — Category column is now indexed in LIKE fallback search, so searching for "regressions" within the regressions category actually works. Score normalization no longer compresses ranges artificially.

What's New in v1.1

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,
  "enableGlobalContext": true,
  "globalContextDir": "~/.repomemory/global"
}

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

Global context config:

• enableGlobalContext: true (default) — set to false to disable global context and behave like v1.1
• globalContextDir: "~/.repomemory/global" (default) — path to global developer context

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