{
"markdown": "\n\n# repomemory\n\n**Your codebase never forgets.**\n\nAI agents lose context every session. repomemory fixes that — one command creates a persistent, searchable knowledge base that any AI tool can read, search, and write to.\n\n[](https://www.npmjs.com/package/repomemory)\n[](https://www.npmjs.com/package/repomemory)\n[](https://github.com/DanielGuru/repomemory/blob/main/LICENSE)\n[](https://github.com/DanielGuru/repomemory/actions)\n\n```bash\nnpx repomemory go\n```\n\n
\n\n---\n\n\n\n\n\n
\n\n## The Problem\n\nEvery time you open a project with Claude Code, Cursor, Copilot, or any AI coding agent:\n\n- It re-discovers your architecture from scratch\n- It proposes changes that were already debated and rejected\n- It re-introduces bugs that were already fixed\n\nYour `CLAUDE.md` / `.cursorrules` helps, but it's static and gets stale.\n\n## The Solution\n\n```\n.context/\n├── index.md ← Quick orientation (loaded every session)\n├── facts/ ← Architecture, database, deployment\n├── decisions/ ← \"We chose Drizzle over Prisma because...\"\n├── regressions/ ← \"This broke before. Here's what happened.\"\n├── preferences/ ← Your coding style — follows you across all repos\n├── sessions/ ← Auto-captured AI session summaries\n└── changelog/ ← Monthly git history syncs\n```\n\n**Facts** tell agents how things work. **Decisions** prevent re-debating. **Regressions** prevent re-breaking. **Preferences** teach agents how you code.\n\n## Quick Start\n\n### With an API key (Claude Code, terminal workflows)\n\n```bash\nnpx repomemory go\n```\n\nOne command: sets up global profile, creates `.context/`, configures Claude Code + Cursor, runs AI analysis, prints CLAUDE.md instructions.\n\n### With Cursor (no API key needed)\n\n```bash\nnpx repomemory setup cursor\n```\n\nThis installs everything Cursor needs:\n- **MCP server** in `~/.cursor/mcp.json` (auto-starts repomemory in every project)\n- **Rules** in `.cursor/rules/repomemory.mdc` (teaches Cursor's AI to use context)\n- **6 commands** in `.cursor/commands/` (run with `/` in Cursor chat)\n\nThen in Cursor chat, type:\n```\n/repomemory-analyze\n```\n\nCursor's own AI scans your repo and populates `.context/` via the MCP tools. No external API key required — your Cursor subscription handles it.\n\n**Available Cursor commands:**\n\n| Command | What it does |\n|---------|-------------|\n| `/repomemory-analyze` | Full repo analysis — populates facts, decisions, index |\n| `/repomemory-orient` | Quick orientation at start of session |\n| `/repomemory-search` | Search the knowledge base |\n| `/repomemory-record` | Record a fact, decision, or regression |\n| `/repomemory-session` | Save a session summary |\n| `/repomemory-status` | Show context coverage |\n\n### Guided wizard\n\n```bash\nnpx repomemory wizard\n```\n\nWalks 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.\n\n### Non-interactive (CI-safe)\n\n```bash\nnpx repomemory go --yes --provider anthropic --embedding-provider gemini --max-files 80\n```\n\nNo prompts when `--yes` / `--defaults` / `--no-prompt` is used.\n\n## MCP Server — Agents With Real Memory\n\nThe real power is the MCP server. When configured via `repomemory setup claude`, it auto-starts with Claude Code and gives agents 7 tools:\n\n| Tool | What It Does |\n|------|-------------|\n| `context_search` | Hybrid keyword + semantic search across repo + global context |\n| `context_auto_orient` | One-call orientation: index, preferences, recent sessions |\n| `context_write` | Write entries with smart scope routing (preferences → global) |\n| `context_read` | Read full content, repo-first with global fallback |\n| `context_list` | Browse entries with `[repo]`/`[global]` provenance tags |\n| `context_risk` | Assess modification risk — hotspots, hidden coupling, bus factor |\n| `context_delete` | Remove stale knowledge |\n\n```\nAgent: \"Let me orient myself in this project...\"\n→ context_auto_orient()\n→ Returns: project overview, preferences, recent sessions, recent changes\n\nAgent: \"Let me search for context about the auth flow...\"\n→ context_search(\"authentication flow\")\n→ Auto-routes to facts/ category, returns compact results\n\nAgent: \"I found a race condition. Let me record this.\"\n→ context_write(category=\"regressions\", filename=\"token-refresh-race\", content=\"...\")\n→ Persisted. Detects if it supersedes an existing entry.\n```\n\nSessions are auto-captured on shutdown. Zero config — `repomemory setup claude` handles everything.\n\n## Supported Tools\n\n| Tool | Integration | API Key Required? |\n|------|------------|-------------------|\n| **Claude Code** | MCP server (auto-starts) + post-commit hook | Yes (for analysis) |\n| **Cursor** | MCP server + rules + 6 slash commands | **No** — uses Cursor's built-in AI |\n| **GitHub Copilot** | `copilot-instructions.md` | Yes (for analysis) |\n| **Windsurf** | `.windsurfrules` | Yes (for analysis) |\n| **Cline** | `.clinerules` | Yes (for analysis) |\n| **Aider** | `.aider.conf.yml` | Yes (for analysis) |\n| **Continue** | `.continue/rules/` | Yes (for analysis) |\n\n> **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).\n\n## Supported Providers\n\n| Provider | Models | Env Variable |\n|----------|--------|-------------|\n| `anthropic` | claude-sonnet-4-6, claude-opus-4-6 | `ANTHROPIC_API_KEY` |\n| `openai` | gpt-4o, o3-mini | `OPENAI_API_KEY` |\n| `gemini` | gemini-2.0-flash, gemini-2.5-pro | `GEMINI_API_KEY` / `GOOGLE_API_KEY` |\n| `grok` | grok-3, grok-3-mini | `GROK_API_KEY` / `XAI_API_KEY` |\n\n**Embeddings** (optional, for semantic search): Gemini `text-embedding-004` (free, default) or OpenAI `text-embedding-3-small`. Auto-detected from available API keys.\n\n## All Commands\n\n```bash\nrepomemory go # One-command setup (add --yes for non-interactive)\nrepomemory wizard # Interactive guided setup\nrepomemory analyze # AI-powered repo analysis\nrepomemory analyze --merge # Update without overwriting edits\nrepomemory analyze --dry-run # Preview without API call\nrepomemory search # Search knowledge base from terminal\nrepomemory status # Coverage and freshness report\nrepomemory doctor # Diagnostics and health check\nrepomemory dashboard # Local web UI (localhost:3333)\nrepomemory risk # Hotspots, coupling, ownership analysis\nrepomemory risk -f src/auth.ts # Targeted risk assessment for specific files\nrepomemory sync # Sync git history to changelog\nrepomemory setup # Configure Claude/Cursor/Copilot/etc\nrepomemory hook install # Auto-sync changelog on commits\nrepomemory global list # Manage global developer context\nrepomemory global export # Export global context as JSON\n```\n\n## Configuration\n\n`.repomemory.json` in your repo root (all fields optional):\n\n```json\n{\n \"provider\": \"anthropic\",\n \"model\": \"claude-sonnet-4-6\",\n \"embeddingProvider\": \"gemini\",\n \"hybridAlpha\": 0.5,\n \"maxFilesForAnalysis\": 80,\n \"enableGlobalContext\": true\n}\n```\n\nCustom `ignorePatterns` and `keyFilePatterns` are **additive** — they extend built-in defaults, not replace them.\n\n## Why Not Just CLAUDE.md?\n\n| | CLAUDE.md | repomemory |\n|--|-----------|------------|\n| **Maintenance** | Manual | AI-generated + agent-maintained |\n| **Search** | Load everything | Hybrid keyword + semantic |\n| **Cross-tool** | Claude Code only | 7 tools supported |\n| **Team knowledge** | One person writes | Every AI session contributes |\n| **Decisions** | Mixed in with instructions | Structured, searchable |\n| **Regressions** | Not tracked | Prevents repeat bugs |\n| **Sessions** | Not tracked | Auto-captured on shutdown |\n| **Freshness** | Unknown | Staleness detection + auto-purge |\n\nrepomemory doesn't replace `CLAUDE.md` — it complements it. `CLAUDE.md` is for instructions and rules. `.context/` holds the knowledge that grows over time.\n\n## Contributing\n\nSee [CONTRIBUTING.md](.github/CONTRIBUTING.md) for development setup, testing, and contribution guidelines.\n\n## License\n\nMIT\n\n---\n\n\n\n**Built for developers who are tired of AI agents forgetting everything between sessions.**\n\n[Report Bug](https://github.com/DanielGuru/repomemory/issues) · [Request Feature](https://github.com/DanielGuru/repomemory/issues) · [npm](https://www.npmjs.com/package/repomemory)\n\n
\n",
"bytes": 9190,
"sha": "2957379d1349d4c85bb3c3f4ba77ddde6181fc430678cc275271efd94704962e",
"repo_slug": "danielguru/repomemory",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_danielguru_repomemory_95d59cfe/readme"
}