repomemory: Instructions file for Claude Code

repomemory — Agent Instructions

Repository Memory (repomemory)

This repo uses repomemory for persistent AI memory.

IMPORTANT: Before starting ANY task, you MUST call context_search with relevant keywords. This is NOT optional. The knowledge base contains architecture docs, past decisions, and known regressions that WILL save you from mistakes. Do NOT skip this step even if the task seems simple.

ALWAYS at the start of every task:

1. Call context_search with keywords related to your task
2. If this is a new session, call context_auto_orient for a full project overview
3. NEVER propose changes without first checking for past decisions

During your session:

• ALWAYS use context_write to record discoveries, decisions, and gotchas
• ALWAYS use context_delete to remove stale or incorrect knowledge
• Record coding preferences in context_write(category="preferences", ...)

Before modifying code:

• You MUST search for known regressions related to the component
• You MUST check for past decisions before proposing alternatives
• Call context_risk with the file paths you plan to modify — it reveals hidden coupling (files that must change together), ownership concentration, and churn hotspots

At end of session (REQUIRED):

• Write a session summary: context_write(category="sessions", ...)
• Route discoveries to the right category (facts/, decisions/, preferences/)

What This Is

A CLI tool + MCP server that gives AI coding agents persistent, structured memory for repositories. Agents can search, write, and delete knowledge that persists across sessions. Features hybrid keyword + semantic search, auto-session capture, intelligent category routing, auto-purge detection, and global developer context that follows you across all repos.

npm package: repomemory Repo: https://github.com/DanielGuru/repomemory

Architecture

src/
├── index.ts                  # CLI entry point (Commander.js). 11 commands. Global error handlers.
├── commands/
│   ├── init.ts               # Scaffolds .context/ directory + .repomemory.json config.
│   │                           Exports CLAUDE_MD_BLOCK with MUST/ALWAYS agent instructions.
│   ├── analyze.ts            # AI-powered repo analysis. System prompt, orchestration,
│   │                           spinner, dry-run, merge mode, retry with backoff.
│   ├── sync.ts               # Reads git log → writes to .context/changelog/YYYY-MM.md
│   │                           with commit hash deduplication.
│   ├── serve.ts              # Thin wrapper that calls startMcpServer()
│   ├── setup.ts              # Configures 7 tools: Claude, Cursor, Copilot, Windsurf,
│   │                           Cline, Aider, Continue.
│   ├── status.ts             # Beautiful coverage bars, freshness indicators, suggestions.
│   ├── wizard.ts             # Interactive guided setup using @clack/prompts.
│   ├── dashboard.ts          # Localhost web UI with edit, server-side search, export.
│   ├── hook.ts               # Git post-commit hook install/uninstall.
│   ├── go.ts                 # One-command setup: init + analyze + setup claude + global profile.
│   ├── search.ts             # CLI search across repo + global context. Hybrid FTS5 + vector.
│   ├── risk.ts               # Git intelligence CLI: hotspots, co-change, ownership analysis.
│   └── global.ts             # Manage global developer context (~/.repomemory/global/).
│                               list, read, write, delete, export, import subcommands.
├── mcp/
│   └── server.ts             # MCP server. 7 tools + 2 prompts + resources.
│                               Dual-store: repo (.context/) + global (~/.repomemory/global/).
│                               Scope routing: preferences→global, everything else→repo.
│                               Session tracking, auto-capture on shutdown,
│                               intelligent category routing, auto-purge detection,
│                               progressive disclosure (compact/full), write-nudge.
└── lib/
    ├── ai-provider.ts        # Multi-provider abstraction (Anthropic, OpenAI, Gemini, Grok).
    │                           Anthropic uses streaming. Gemini uses systemInstruction.
    │                           AIError class with isRetryable. Cost estimation.
    ├── embeddings.ts          # Embedding provider abstraction (OpenAI, Gemini).
    │                           cosineSimilarity(). createEmbeddingProvider() with auto-detect.
    ├── config.ts              # Loads .repomemory.json with Zod validation. Single source
    │                           of DEFAULT_CONFIG truth. Embedding + global context config.
    │                           resolveGlobalDir() for ~ expansion.
    ├── context-store.ts       # CRUD + delete for .context/ files. Category validation.
    │                           Sanitized filenames with NFKD unicode normalization.
    │                           forAbsolutePath() factory for global store.
    ├── search.ts              # sql.js (Wasm) FTS5 + optional vector search.
    │                           Hybrid scoring (alpha * keyword + (1-alpha) * semantic).
    │                           DB persistence (loads from disk on restart).
    │                           Incremental indexEntry() and removeEntry() methods.
    ├── json-repair.ts         # JSON extraction/repair pipeline. extractJSON, fixJsonNewlines,
    │                           repairTruncatedJSON. Extracted from analyze.ts for testability.
    ├── git.ts                 # Git info extraction using execFileSync (no shell injection).
    │                           getLastCommitHash() for sync deduplication.
    ├── git-intelligence.ts    # Git history analysis: hotspots (churn×commits), co-change
    │                           detection (Jaccard similarity), file ownership & bus factor.
    │                           analyzeGitIntelligence() for overview, assessFileRisk() for targets.
    └── repo-scanner.ts        # Walks repo tree respecting .gitignore, detects languages/
                                frameworks across JS, Python, Rust, Go, Ruby ecosystems.