# 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](./README-homelab-kb.md) for the Andromeda homelab KB (facts, services, patterns, runbooks, HTTP API on port 3456).

## Install

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

## Quick Start

```bash
# 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`:

```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

| Tool | Description |
|---|---|
| `get_context` | Retrieve context for a repo + automatic freshness/drift check |
| `save_context` | Save full repo context (creates new version) |
| `update_context` | Partial update (only changed fields) |
| `auto_update_context` | Scan repo on disk, auto-detect changes, merge additively |
| `list_repos` | List all cached repos |
| `search_repos` | Full-text search across repos |
| `get_repo_history` | Version history for a repo |
| `delete_repo` | Remove a repo and its history |
| `save_pattern` | Save a cross-repo pattern |
| `get_patterns` | Get patterns by tech stack or tags |
| `search_patterns` | Search across patterns |

## 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.