-
Notifications
You must be signed in to change notification settings - Fork 3
Home
Persistent local memory for Claude Code. Every tool call, every file edit, every thinking block from every session — stored verbatim on your machine. Searchable, replayable, and recallable by fuzzy natural-language questions. Zero API calls. Zero summaries. Zero decisions made by an AI about what's worth remembering.
Everyone is solving AI memory by making the context window bigger. 1M tokens. 2M tokens. Context-infinite.
Longhand goes the other direction. The model doesn't need to carry the memory. The disk does.
Your past sessions are already on disk, written by Claude Code itself, in JSONL files that contain every event verbatim. Longhand reads those files, indexes them locally, and gives you semantic recall over your entire history without sending a token through anyone else's API.
Local. Complete. Yours.
- Getting Started — install, setup, first recall in under 5 minutes
- MCP Tools Reference — the 17 tools Claude agents can call, with a decision tree and token budget
- CLI Reference — the 21 commands you can run from the terminal
- Architecture — parser → extractors → analysis → storage → recall
- Configuration — hook tuning, relevance thresholds, injection size
- Security — trust boundaries and threat model
- Troubleshooting — hook not firing, MCP not showing up, ingest slow
- Roadmap — known gaps, planned features, help wanted
pip install longhand
longhand setup
longhand recall "that stripe webhook bug from last week"That's it. longhand setup ingests your existing Claude Code history, installs the SessionEnd hook so new sessions auto-ingest, registers the MCP server so Claude can call recall during live sessions, and runs longhand doctor to verify everything wired correctly.
pip install --upgrade longhandComing from 0.5.x? v0.6.0 fixed two failure modes that could cause recall_project_status to miss real sessions: multi-project sessions were attributed to $HOME (because project inference only looked at the first-event cwd), and there was no reconciliation for transcripts whose SessionEnd hook failed silently. Run this once to replay your history with the corrected logic:
longhand reconcile --fixIdempotent. Prints a summary of drift (how many sessions were un-ingested, how many had project_id IS NULL) and, with --fix, re-ingests those buckets using the improved attribution. Typical throughput: ~1–2 sessions/sec.
Coming from 0.5.8 or earlier? Chain the upgrades — longhand reconcile --fix && longhand reanalyze. The first replays attribution; the second rebuilds episode summaries for the intent-framed-query improvements shipped in v0.5.10.
The most common question: does Longhand consume a lot of tokens when Claude uses it?
No — every MCP tool is capped by design. A full recall across 100+ sessions returns ~4K tokens. Reading one raw session JSONL directly costs 10–50× more. Longhand itself makes zero API calls; the only tokens consumed are the MCP payload Claude reads back. Full breakdown, per-tool caps, and tuning knobs: MCP Tools Reference → Token budget.
v0.6.0 — stable, daily-driver tested, security-audited (zero critical findings). Validated against 131+ real Claude Code sessions across 40+ inferred projects. 182 unit tests passing.
Main repo: github.com/Wynelson94/longhand