Longhand

Longhand

Using Codex too? Share one memory archive between Claude Code and Codex.

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 ~29ms — without a single API call.

Does it use a lot of tokens? No — the tools you'll use most are capped by design. A full recall across 100+ sessions returns ~4K tokens. Reading one raw session JSONL costs 10–50× more. See Token budget for which tools cap output and which don't.

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 1.0.0? This is the release that closes the deprecation window 0.13 opened. Everything removed here has been warning since 0.13.0:

• Four CLI aliases are gone: patterns → recall " ", recap → status --days N, continue → status --session , reanalyze → analyze --all.
• The `reconcile` MCP tool now defaults to a dry run. If you have an agent loop that relied on the implicit heal, pass fix=true explicitly. Dry runs tell you so in the payload.
• Six retired MCP tools left the listing (19 → 13) but still answer forever with a migration note — retired names live in users' own CLAUDE.md files and must never hard-fail.
• New: COMPATIBILITY.md states what 1.x guarantees and what it doesn't.

Your database needs nothing. Migrations are automatic and a 0.11+ store opens on any later 1.x — that's Promise 2, and there's a real 0.11-schema fixture in the test suite proving it.

Upgrading to 1.3.0? Nothing removed, and nothing changes until you ask for it. One new, opt-in capability: longhand backup writes every session's verbatim transcript to a private git repository you own (secret-shaped strings masked in the copy only), and longhand restore rebuilds the archive on a new machine from it. It stays off until backup init has shown you exactly what would be uploaded and you have typed yes. See Backup below and docs/backup.md.

Upgrading to 1.2.x? No removals, just fixes worth knowing about:

• 1.2.3: MCP get_session_timeline's tail now returns the true last N events on sessions over 5,000 events — it used to return the middle. setup's closing hint stopped suggesting recap (removed at 1.0) and now suggests status --days 7. Recall's footers and get_session_timeline's own tool description stopped naming search_in_context (retired from the tool listing at 1.0, though it still answers) and now point at search — the footers spell out the call, search(session_id=…, query=…, context_events=5).
• 1.2.2: recall says so when its top match is much older than the alternatives instead of letting a stale fix read as current (see Recall Example). A Codex context-compaction record (compacted) no longer trips doctor's transcript-format-drift warning.
• 1.2.1: MCP get_session_timeline had a sentinel bug that made every call return exactly one event, ignoring limit/offset, unless tail was passed explicitly — fixed. search's project auto-scoping no longer overrides an explicit session_id.

Upgrading to 0.13.0? Nothing breaks — that release opened the v1.0 deprecation window, so every old name kept working while pointing at its replacement:

• status is now the single resume command: bare status = recent digest (was recap), status unchanged, status --session = session tail (was continue). The old commands still run and print a pointer; they're removed at v1.0.
• Six MCP tools folded into six survivors with identical parameters (search_in_context → search + context_events, get_episode → find_episodes + episode_id, etc. — full table in the CHANGELOG). The retired names still answer, prefixed with a migration note.
• Hooks can no longer exit nonzero — failures become breadcrumbs in ~/.longhand/logs/ and two new doctor rows (Hook errors, Transcript format) keep them visible.
• "Today"/"yesterday" recall windows now follow your local calendar day instead of UTC's; rankings may shift once if you're not in UTC.
• Windows users: this release fixes a serious bug where the ingest-lock liveness check could terminate other longhand processes.
• New: LONGHAND_DATA_DIR relocates the store for the CLI, hooks, and MCP server in one move — except longhand config --set, which always writes ~/.longhand/config.json regardless of the relocated store (#96; --edit is currently a no-op, same issue). status --json / doctor --json for scripting.

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. The in-progress session becomes queryable immediately via list_sessions, get_session_timeline/timeline, get_file_history, and replay_file — it writes events only, no embeddings, so recall and semantic search still need the SessionEnd pass (or a reconcile --fix pass, which re-ingests with analysis) to see it.
• 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). --skip-analysis defers the *other* pass — episode/segment extraction and project/session-level vectors — not event embedding, which always runs, so it trims some time but not the dominant cost:

longhand setup --skip-analysis   # events stored + embedded; episodes/segments deferred

longhand analyze --all # fill in episodes + segments + project/session vectors whenever, safe to background

search, timelines, file history, and commit lookup all work immediately after --skip-analysis — every event is embedded regardless of this flag. recall's episode/segment narrative and recall_project_status need the analyze --all pass to have data to draw on. Typical throughput on an M-class Mac is ~1–2 sessions/sec for full analysis.

*Status: v1.3.1 — stable, daily-driver tested, security-audited (zero critical findings), on PyPI, available as a Claude Code plugin. Validated against 792 real sessions (786 Claude Code, 6 Codex) across 45 inferred projects (measured 2026-09-27). 834 unit tests passing.*

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

---

The Inversion

Everyone is solving AI memory by making the context window bigger. 1M tokens. 2M tokens. Context-infinite. The whole industry is racing in the same direction: make the mod