ContextKeeper

Persistent memory for AI coding agents. Your architectural decisions, preferences, and rationales survive across sessions — automatically injected into every prompt.

The problem

You tell your AI agent "we use Clerk for auth, not NextAuth — Clerk has a hosted UI and a free tier."

Tomorrow, in a new session, the agent suggests NextAuth. Again.

Static CLAUDE.md files are manual to maintain and easy to ignore. Memory tools like Mem0, Letta, and Zep are built for chatbots, not codebases — they don't know what a "scope glob" is.

The fix

ContextKeeper records architectural decisions as plain markdown files in your repo, indexes them with SQLite, and injects relevant ones into every Claude Code session and every prompt via deterministic hooks.

your decisions ──► .contextkeeper/decisions/*.md ──► hook injects into every turn

• Source of truth: markdown in git. Reviewable in PRs. Survives tool churn. Hand-editable.
• Retrieval: deterministic. Path globs + tags + FTS5 + recency. No embeddings. Every result explains why it ranked.
• Recall: 100% reliable. Hooks fire before the model sees your prompt — not at the model's discretion.
• Capture: one MCP tool call. Agent records decisions as you make them. (Auto-extraction from transcripts coming in v0.2.)

Two modes, one engine

| Mode | Use when | Capture | Recall | Conflicts | |---|---|---|---|---| | auto (default) | You want magic. You don't want to think. | Agent records aggressively, no confirmation | Eager hooks inject every turn | Auto-superseded silently | | manual | You want explicit control. | Agent records only when asked | Same hooks; agent reasons over them | Surface as warnings, you decide |

Toggle via CONTEXTKEEPER_MODE=manual or .contextkeeper/config.json. Same data, same files, different aggressiveness.

Install (60 seconds)

# 1. Register the MCP server with Claude Code
claude mcp add contextkeeper -- npx -y contextkeeper-mcp

# 2. Install deterministic recall hooks (one-time, global)
npx contextkeeper-mcp install-hooks

# 3. Start a new Claude Code session in your repo. That's it.

The install-hooks step writes two entries into ~/.claude/settings.json, marked # ckeeper-managed. Inspect or remove anytime:

npx contextkeeper-mcp uninstall-hooks

How it feels

Without ContextKeeper:

You: We use Clerk for auth, the API uses tRPC, and components live in app/(marketing)/. Add a sign-in page. Agent: [reads files, writes code] —next session— You: Add a sign-up page. Agent: I'll set up NextAuth in pages/api/auth/...

With ContextKeeper:

—first session— You: We use Clerk for auth, tRPC for the API, components in app/(marketing)/. Agent: [calls record_decision × 3, silently] —next session, new chat— You: Add a sign-up page. [hook injects: "Use Clerk for auth · API uses tRPC · components live in app/(marketing)/"] Agent: I'll add a Clerk-backed <SignUp /> in app/(marketing)/sign-up/page.tsx.

Architecture

┌──────────────────────┐    MCP/stdio    ┌────────────────────┐
│  Claude Code /       │◄───────────────►│  contextkeeper-mcp │
│  Cursor / Windsurf   │                 │   (Node, ~1k LoC)  │
└──────────┬───────────┘                 └─────────┬──────────┘
           │ SessionStart hook                     │
           │ UserPromptSubmit hook                 │
           │ (deterministic injection)             │
           ▼                                       │
   additionalContext                               │
   (system-prompt block)                           ▼
                                       .contextkeeper/decisions/
                                              *.md
                                              │
                                              ▼
                                       index.sqlite (FTS5)
                                       (rebuildable cache)

| File | Role | |---|---| | src/main.ts | CLI dispatcher (serve, context, relevant, install-hooks, …) | | src/server.ts | MCP server — five tools, mode-aware descriptions | | src/storage.ts | Markdown CRUD with gray-matter frontmatter | | src/index_db.ts | SQLite + FTS5 index, schema-versioned | | src/retrieval.ts | Pure ranking function with explainable reasons[] | | src/conflict.ts | Jaccard similarity for auto-supersede / warning | | src/cli.ts | Hook integration + install-hooks | | src/config.ts | Mode resolution |

Decision file format

---
id: 01HXYZ...
created_at: 2026-05-05T14:22:00Z
updated_at: 2026-05-05T14:22:00Z
status: active
scope:
  - app/api/auth/**
  - lib/auth/**
tags: [auth, security]
confidence: 0.9
supersedes: null
---

# Use Clerk for auth, not NextAuth

Clerk gives us hosted auth UI and a generous free tier...

Comparison

| | ContextKeeper | CLAUDE.md | Mem0 / Zep / Letta | |---|---|---|---| | Source of truth | Markdown in your repo | Markdown in your repo | Vector DB (SaaS) | | Auto-injection | Hooks (deterministic) | Manual reading | API call from agent | | Scoping by file path | ✅ | ❌ | ❌ | | Reviewable in PRs | ✅ | ✅ | ❌ | | Survives tool churn | ✅ | ✅ | ❌ (vendor lock-in) | | Built for code | ✅ | ✅ | ❌ (chatbot-shaped) | | Cloud required | No | No | Yes (most) | | Zero credentials | ✅ | ✅ | ❌ |

Roadmap

v0.1 (current) — manual capture, deterministic recall, two modes.

v0.2 — automatic capture via Stop hook + claude -p extraction. Reuses existing storage/conflict code. Bias toward false negatives. Every captured decision carries a verbatim user-quote audit field.

v0.3 — ckeeper review UX, schema migrations beyond drop-and-rebuild, cross-platform Windows hook installer.

v1.0 — once dogfooded, opinions stabilised, prompt quality measured against a real corpus.

Status

Alpha. Used in anger by the author. Probably has rough edges. Issues and PRs welcome — see CONTRIBUTING.md.

License

MIT — see LICENSE.