Chronicle — v0 MCP Server Skeleton

Automatic, lossless context management for AI coding agents. Select, never summarize.

This is the v0 scaffold described in the Chronicle PRD and the three engineering specs (RRA, GvR, Distiller). It is a working skeleton — the core pipeline runs end to end, offline, with no API key — plus clearly marked stubs for the parts that land in v0.1/v1.

It implements the loop: Capture → Distill → Reconstruct → Serve, exposed as an MCP server any compatible client (Claude Code, Cursor, …) can connect to.

What's real vs. stubbed

| Component | Status | File | | --------------------------------- | ---------------------------------------------------------------------- | ---------------------------- | | Immutable Event Log | Real (SQLite + in-memory) | src/store/* | | Decision Ledger distiller | Real, offline, grounded + supersession | src/distiller/heuristic.ts | | LLM distiller | Stub (prompt + schema defined, model call TODO) | src/distiller/llm.ts | | Reconstruction Ranking Algo (RRA) | Real (5 signals, quota packing, provenance, determinism) | src/rra/* | | Code Knowledge Graph | Partial (v0 proxy: imports + co-edit adjacency) | src/graph/ref-graph.ts | | Symbol extraction | Partial (v0 regex; tree-sitter is the v1 upgrade) | src/capture/symbols.ts | | Embeddings | Partial (v0 offline feature-hashing; real model plugs into Embedder) | src/embeddings.ts | | MCP server | Real (4 tools) | src/server.ts |

The architecture is built so each partial/stub box swaps out behind a stable interface without touching the rest of the system.

Run the offline demo (no install of native deps, no API key)

npm install            # or: npm i --no-save [email protected] for just the demo
npm run demo

The demo replays the auth-token scenario from the Distiller spec and prints:

• the distilled ledger (each node grounded in real event ids),
• a superseded decision (localStorage → httpOnly cookie),
• the reconstructed context window with per-chunk provenance,
• a determinism check and a budget-ceiling check (both must PASS).

Note refreshToken appears in the window via the graph, even though the task only named verifyJWT — that's the structural signal doing its job.

Quickstart — one command, no JSON

No clone, no build, no config file to hand-edit. Run the installer; it detects your client (Claude Code and/or Cursor) and registers Chronicle for you:

# this project only
npx -y @chroniclemcp/mcp init

# or: on in every project, run once
npx -y @chroniclemcp/mcp init --global

Restart your editor/agent and Chronicle is live. On first run it cold-starts its memory from the project's own rules files and git history. The store is local (./.chronicle/chronicle.db); --project . in the written config keeps a separate store per project even under a global install.

Hands-off by default (Claude Code)

init also wires two Claude Code hooks so you never call a tool by hand:

• Auto-capture (PostToolUse): edits, test runs, and errors are recorded as you work, no agent cooperation needed.
• Auto-recall (SessionStart): the reconstructed window is injected into every new session, after /clear, and after a compaction, so the agent resumes with your prior decisions, rejected approaches, and recent work already in context, even when auto-compaction would otherwise have dropped the detail.

Pass --no-hooks to register the MCP server only. Cursor has no equivalent hooks today, so on Cursor capture and recall run through the MCP tools when the agent calls them (the init summary states this).

Optional: context advisor. init --advise adds a UserPromptSubmit hook that watches how full the window is getting and, once it crosses a threshold, nudges you to run /clear (lossless, auto-recall restores your state, so it's a single safe keystroke). Default threshold 70%; set CHRONICLE_ADVISE_THRESHOLD=0.5 for halfway, and CHRONICLE_CONTEXT_LIMIT to match your model's window. It's opt-in because it's the one feature that interrupts. Note: Claude Code does not let an extension read exact usage or run /clear itself, so the advisor estimates fill from the transcript and the clear stays your keystroke.

Optional: per-turn freshness. init --per-turn adds a UserPromptSubmit hook that re-injects relevant memory mid-session, but only when your focus has clearly shifted (measured by how much of the window's structural reach is new), so it stays silent turn to turn and doesn't bloat the conversation. Useful if you range across unrelated parts of a codebase in one session; otherwise SessionStart recall and the agent's own chronicle_reconstruct already cover you. Off by default.

Inspect or print the current memory from the terminal any time:

npx -y @chroniclemcp/mcp status --project .       # ledger + recent-log readout
npx -y @chroniclemcp/mcp reconstruct --project .  # the window the hook injects

Claude Code — claude mcp add chronicle -- npx -y @chroniclemcp/mcp (add --scope user for every project).

Or add to .mcp.json in your project root (Cursor: .cursor/mcp.json or the global ~/.cursor/mcp.json):

{
  "mcpServers": {
    "chronicle": {
      "command": "npx",
      "args": ["-y", "@chroniclemcp/mcp", "--project", "."]
    }
  }
}

The same snippet ships as .mcp.json.example.

Local development (from a clone)

npm install
npm run build
npm start            # node dist/server.js --project .

Tools exposed:

• chronicle_capture — append an event to the immutable log (auto-runs the distiller)
• chronicle_reconstruct — get the optimal context window for the current task
• chronicle_set_thread — set the live working objective (persists across sessions)
• chronicle_status — ledger + recent-log readout

State is local: ./.chronicle/chronicle.db. No cloud, no accounts (that's v2).

How it maps to the specs

• SPEC-001 (RRA): src/rra/signals.ts (the 5 signals), src/rra/packing.ts (4-stage quota knapsack + stable→volatile ordering), src/rra/reconstruct.ts (pool → score → pack → emit, with a determinism receipt).
• SPEC-003 (Distiller): src/distiller/heuristic.ts — grounded extraction (every node cites ≥1 source event), dedupe/merge, and supersession (demote-and-link, never delete). Content-derived ids give idempotency.
• SPEC-002 (GvR): the Embedder/RefGraph seams are where the graph-vs-RAG experiment plugs in; RRAConfig.weights is the surface the benchmark tunes.

Next steps toward v1

1. Replace HashEmbedder with a real embedding model (ApiEmbedder).
2. Replace RefGraph + regex symbols with a tree-sitter Code Knowledge Graph.
3. Implement LlmDistiller (cheap model) sharing the heuristic's validate path.
4. Persist lastWindowRefs for the stability signal across turns.
5. Build the GvR harness (SPEC-002) and tune RRAConfig.weights on it.
6. Add the dashboard (browse ledger, inspect any turn's reconstructed window).

MIT.