长手记忆

Longhand

Persistent local memory for Claude Code. Every tool call, every file edit, every thinking block from every Claude Code 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.

Claude Code quietly rotates your session files after a few weeks. Longhand captures them into SQLite before they're gone. Once ingested, your history stays forever — even after the source JSONL files are deleted. Install early; the past you don't capture is unrecoverable.

If you have 20+ Claude Code sessions in ~/.claude/projects/, Longhand can search across every fix, decision, and conversation you've had in ~56ms — without a single API call.

Does it use a lot of tokens? No — every tool is capped by design. A full recall across 100+ sessions returns ~4K tokens. Reading one raw session JSONL costs 10–50× more. See Token budget.

pip install longhand
longhand setup        # ingest history + install hooks + configure MCP
longhand recall "that stripe webhook bug from last week"

Want to kick the tires first? Run longhand demo for a 60-second walkthrough on a fake 3-session sample corpus — your real ~/.claude and ~/.longhand are not touched. The demo seeds a sandboxed store with a Stripe-webhook bug + Supabase auth migration + downstream 401 fix, then runs cross-session recall and project-status so you can see what the output looks like before committing.

pip install longhand
longhand demo         # sandboxed; cleans up afterwards (pass --keep to explore)

Upgrading to 0.9.0? Live ingestion captures sessions in flight, plan history is preserved as first-class data, and an optional reconciler job keeps the index honest in the background:

• New longhand ingest-live command runs from Claude Code's Stop hook to tail the active transcript between assistant turns. Sessions show up in recall while you're still working, not after they end.
• New longhand plans list command and list_plans MCP tool surface every Write/Edit to ~/.claude/plans/*.md across your entire history. Plans are now extracted as their own entity alongside episodes.
• New longhand schedule install-reconciler installs an optional launchd job that runs reconcile --fix periodically — catches anything the live and post-session hooks missed without you ever thinking about it.
• The Stop hook coexists with the existing SessionEnd hook: live tails the transcript as it grows; SessionEnd does the full analysis pass when the session closes.

Upgrading to 0.8.1? Staleness signals now propagate everywhere they belong, and reconcile is an MCP tool — Claude can self-heal the index from inside a session:

• search and list_sessions now wrap the response with stale: true + stale_reason when the project they're scoped to has on-disk transcripts not yet ingested. Pre-v0.8.1 these returned clean-looking empty results (same silent-failure shape recall_project_status was built to catch — just one layer up).
• New reconcile MCP tool wraps longhand reconcile --fix. After a staleness banner fires, Claude calls reconcile directly instead of asking the user to run a CLI command.
• list_sessions default limit raised from 20 to 50 — active days routinely cross 5+ projects across 5+ sessions; the old default truncated reviews silently.

Upgrading from 0.7.x or earlier? Cleaner recall narratives, plus a real bug-finding test layer underneath (from 0.8.0):

• Pre-v0.8 _compose_fix_summary prepended a literal "Intent:" label to half of all extracted episodes (49% of the reference corpus). The label leaked into every recall narrative for those episodes. Migration v4 strips it from existing rows on first store open — no command needed.
• Diff content in fix_summary now truncates at whitespace boundaries with a visible …, instead of landing mid-token (phoneNum', family?:', strin'). Forward-only.
• Narrative footer "Other matches" lines now include the session id so you can drill in.
• New canary harness (tests/fixtures/corpus/) anchors regression tests to real shipped bugs. New recall validator (scripts/recall_diff.py) snapshots and diffs ranking results against your live corpus — catches regressions pytest can't see.

pip install --upgrade longhand
longhand recall "..."   # migration runs transparently on first open

If you're also coming from 0.5.x, run longhand reconcile --fix once to re-attribute multi-project sessions per the v0.6 inference improvements (cd-into-project sessions now attribute to the project where most work happened, not the first-event cwd). If you're on 0.5.8 or earlier, chain them: longhand reconcile --fix && longhand analyze --all. Both are idempotent.

Large history? (>1 GB of ~/.claude/projects) Expect the first-time backfill to take 10–30 minutes on an M-class Mac — most of that wall time is the embedding model running on all your cores (which is why you'll see triple-digit CPU%; that's ONNX doing its job, not a hang). To get a working store faster, use the fast-path:

longhand setup --skip-analysis   # SQLite only; works in ~1 min for multi-GB corpora
longhand analyze --all           # fill in episodes + vectors whenever, safe to background

Exact-text search, timelines, file history, and commit lookup all work after --skip-analysis. Semantic recall needs the analyze --all pass to complete. Typical throughput on an M-class Mac is ~1–2 sessions/sec for full analysis.

Status: v0.11.0 — stable, daily-driver tested, security-audited (zero critical findings), on PyPI, available as a Claude Code plugin. Validated against 246 real Claude Code sessions across 54 inferred projects. 316 unit tests passing.

Full docs: Longhand Wiki — getting started, CLI reference, MCP tools reference, architecture, and troubleshooting.

---

What's in the archive?

longhand stats longhand sessions longhand projects