handoff-mcp

Your agent's memory between sessions. Persistent, cross-project hand-off for Claude over the Model Context Protocol — it remembers the goal, the decisions, the dead-ends, and what's next, so the next session never starts from zero.

Claude forgets everything between sessions. handoff-mcp gives it a memory that survives the context window: it tracks the progress of your work — goals, decisions and their rationale, dead-ends, open questions, the next step — and at the boundary of a session produces a prioritised, token-budgeted brief so the next session resumes already knowing where you left off.

It is not a context dump. Two things make it different from similarity-based memory stores (mem0 / OpenMemory style):

1. Temporal supersession. A new decision retracts an old one; retracted decisions never appear in a future brief. Memory reflects the current state of the world, not a flat pile of contradictory facts.
2. Deterministic brief. The brief is assembled by an explainable ranker (recency + importance + supersession), not by an LLM — so it is reproducible and stays within a token budget (a soft cap on event content; see Limitations).
3. Your store, multi-device. The vault is your own private git repo, not a hosted service — so memory can follow you across machines (pull-on-start, push-on-checkpoint, conflict-free entity merges) with zero vendor lock. See Multi-device sync.

Status: v0.4, early. The core (vault, brief, supersession, keyword search, cross-project recall) is tested and stable; the semantic, consolidation, importer, and multi-device sync layers are optional and newer. It leans on the agent calling the tools at the right moments — see Limitations for the honest edges.

It is also cross-project: one vault, namespaced per project. The brief is project-scoped (where did I leave off here), but search_memory recalls across all projects — so when you say "in one of my projects we did X", Claude can find and pull that decision out of another project.

Contents

• Demo: two sessions
• Benchmarks
• How it works
• MCP tools
• Cost & API keys
• Semantic recall (optional)
• Memory consolidation (optional)
• Import existing history
• Quickstart
• Connect your MCP client — Claude, Cursor, Codex, Kilo Code, …
• Where your memory lives
• Multi-device sync (optional)
• Agent integration
• Limitations
• Development
• License

Demo: two sessions

python examples/two_sessions_demo.py — session 1 works and stops; session 2 is a fresh process that resumes from the brief alone.

Session 1 logs its progress (and changes its mind once):

log_event("goal",     "Ship the finance agent: income/expense tracking…")
d = log_event("decision", "Store transactions in a flat JSON file.")
log_event("decision", "Use SQLite instead of JSON — need queries.", supersedes=[d])  # retracts ↑
note_entity("Architecture", "SQLite-backed; LLM summary calls run in a worker.")     # durable
log_event("deadend",  "Provider streaming API times out on long months; needs chunking.")
log_event("question", "Recurring transactions: templates or materialised rows?")
log_event("next_step","Write the SQLite schema, then the ingest function.")
checkpoint("Chose SQLite; finance schema is next.")

Session 2 calls get_brief() and gets back only the current state — the retracted JSON decision is gone:

# Hand-off brief — agent-hub

## Goal
- Ship the finance agent: income/expense tracking with scheduled summaries.
## Next step
- Write the SQLite schema for transactions and categories, then the ingest function.
## Decisions
- Use SQLite for transactions instead of JSON — need queries for summaries. See [[Architecture]].
## Dead ends (tried & failed)
- Tried the provider's streaming API for the summary job — times out on long months. Don't retry without chunking.
## Open questions
- Should recurring transactions be modelled as templates or materialised rows?
## Related knowledge
- [[Architecture]] — SQLite-backed; LLM summary calls run in a worker.

The retracted "flat JSON file" decision never appears. The graph-linked [[Architecture]] note is pulled in automatically. The brief is ~170 tokens.

And cross-project recall — search_memory("timeout chunking", scope="all") pulls a decision out of a different project:

- [hermes]    In the Hermes project we solved long-job timeouts by chunking requests.
- [agent-hub] Tried the provider's streaming API for the summary job — times out on long months…

Benchmarks

Two offline, deterministic benchmarks — no LLM, no network — so they regenerate identically anywhere and are pinned by tests/test_benchmark.py. Full numbers, methodology, and how to reproduce: benchmarks/RESULTS.md.

1. Supersession in isolation (benchmarks/supersession_benchmark.py). A project's decisions evolve across 8 statements over 4 topics; each has one decision a later one retracts (JSON→SQLite, cookies→JWT, …). Retrieved by decision (so every stale fact is reachable), the flat log vs the active view:

Supersession removes exactly the retracted decisions while keeping every current one — and scoring current kept too means an empty answer can't pass as a win. A similarity store with no notion of one fact retiring another behaves like the OFF row.

2. Brief vs naive dump (benchmarks/brief_reconstruction.py). What a resuming session actually reads — the budgeted, supersession-aware brief vs pasting back the whole log. As history grows the dump balloons and keeps carrying every retraction; the brief stays bounded (a soft cap) and contradiction-free while retaining all key items (e.g. at 228 events: 3063→217 tokens, 14×, 3 contradictions → 0).

These measure the mechanism honestly rather than staging a head-to-head against another store — a fair cross-system run needs both under identical retrieval plus an LLM endpoint we can't reproduce in CI (see ADR-0008).

"Tokens" here and elsewhere in this README are estimated as len(text) / 4 (model-agnostic), not counted with a real tokenizer.

How it works

The markdown vault is the source of truth — human-readable, openable in Obsidian, your data on your disk. The SQLite + FTS5 index is derived from the vault and can be rebuilt at any time; it powers ranking, the token budget, and cross-project full-text search.

See docs/architecture.md and the ADRs for the design rationale.

MCP tools

Also exposed: an MCP resource session://brief and a prompt resume for auto-loading the brief at the top of a session.

log_event types: goal, decision, deadend, file, question, next_step.

Cost & API keys

No subscription. No required API keys. The core is free and fully local — your memory is plain files on your disk, and handoff-mcp never phones home (no hosted service, no telemetry).