repo-ctx

A unified context layer for LLMs. Stores both in-repo context (what this repo is) and cross-repo patterns (shared knowledge across projects) in a global SQLite database. Any MCP-compatible IDE (Cursor, Claude Desktop) gets instant context without re-exploring.

Homelab Knowledge Base: See README-homelab-kb.md for the Andromeda homelab KB (facts, services, patterns, runbooks, HTTP API on port 3456).

Install

cd ~/repo-ctx
npm install
npm run build
npm install -g .

Related MCP server: sill-ensoul

Quick Start

# Initialize the database
repo-ctx init

# Import existing context from ~/.context_store/
repo-ctx import --legacy

# List cached repos
repo-ctx list

# Get full context for a repo (pipe-friendly)
repo-ctx get myrepo
repo-ctx get myrepo --json | pbcopy

# Search across all repos
repo-ctx search "fastapi"

# List cross-repo patterns
repo-ctx patterns

# Export entire DB as JSON (for backup or sharing)
repo-ctx export > context-backup.json

# Import on another machine
repo-ctx import context-backup.json

Cursor Integration

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "repo-ctx": {
      "command": "node",
      "args": ["/path/to/repo-ctx/dist/index.js", "serve"]
    }
  }
}

The LLM is then instructed (via AGENTS.md or Cursor rules) to:

1. Before exploring any repo: check for cached context via get_context

2. After exploring: save context via save_context

3. After significant tasks: call auto_update_context to auto-detect changes

4. When get_context reports drift: call auto_update_context to refresh

5. When noticing patterns: save them via save_pattern

MCP Tools

How It Works

In-Repo Context

Each repo gets a structured context entry: overview, tech stack, file tree, key files, architecture, and notes. Context is versioned — every update creates a new version, old ones are preserved.

Cross-Repo Patterns

When the LLM notices a pattern used across repos (e.g. "JWT auth middleware"), it saves it as a pattern tagged with the repos where it was seen. When working in any repo, relevant patterns are surfaced based on the tech stack.

Automatic Staleness Detection

On every get_context call, the server compares stored fingerprints (git hash, dependency file hash, file tree hash) against the current state. If drift is detected, the response includes an action_hint telling the agent to call auto_update_context.

Auto-Update

auto_update_context scans the repo on disk using convention-based heuristics (file names, extensions, directory structure) to detect key files, tech stack, sub-projects, and patterns. It merges additively — never overwrites manually-set fields like overview, architecture, or notes.

Database

Everything lives in ~/.repo-context/context.db — a single portable SQLite file. Copy it to another machine, install repo-ctx, and every LLM has your full knowledge base.