Longhand
About
Persistent local memory for Claude Code, Zero API calls, zero summaries, zero AI deciding what matters.
Details
- Author
- wynelson94
- Categories
- Productivity, AI, Developer Tools
Jump to
Setup
Install Longhand in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/wynelson94/longhand
Follow the installation instructions in the repository README, then restart your MCP client.
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 fullrecallacross 100+ sessions returns ~4K tokens. Reading one raw session JSONL costs 10–50× more. SeeToken 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?Runlonghand demofor a 60-second walkthrough on a fake 3-session sample corpus — your real~/.claudeand~/.longhandare 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 "<topic>",recap→status --days N,continue→status --session <prefix>,reanalyze→analyze --all.
- ThereconcileMCP tool now defaults to a dry run.If you have an agent loop that relied on the implicit heal, passfix=trueexplicitly. Dry runs tell you so in the payload.
- Six retired MCP tools left the listing (19 → 13) butstill answer foreverwith a migration note — retired names live in users' ownCLAUDE.mdfiles and must never hard-fail.
- New:COMPATIBILITY.mdstates 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 0.13.0?Nothing breaks — that release opened the v1.0 deprecation window, so every old name kept working while pointing at its replacement:
- statusis now the single resume command: barestatus= recent digest (wasrecap),status <project>unchanged,status --session <prefix>= session tail (wascontinue). 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 newdoctorrows (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_DIRrelocates the store for the CLI, hooks, and MCP server in one move;status --json/doctor --jsonfor 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:
- Newlonghand ingest-livecommand runs from Claude Code'sStophook to tail the active transcript between assistant turns. Sessions show up inrecallwhile you're still working, not after they end.
- Newlonghand plans listcommand andlist_plansMCP tool surface every Write/Edit to~/.claude/plans/.mdacross your entire history. Plans are now extracted as their own entity alongside episodes.
- Newlonghand schedule install-reconcilerinstalls an optional launchd job that runsreconcile --fixperiodically — 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, andreconcileis an MCP tool — Claude can self-heal the index from inside a session:
- searchandlist_sessionsnow wrap the response withstale: true+stale_reasonwhen 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 shaperecall_project_statuswas built to catch — just one layer up).
- NewreconcileMCP tool wrapslonghand reconcile --fix. After a staleness banner fires, Claude callsreconciledirectly instead of asking the user to run a CLI command.
- list_sessionsdefaultlimitraised 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_summaryprepended 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 infix_summarynow 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, runlonghand reconcile --fixonce 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. Semanticrecallneeds theanalyze --allpass to complete. Typical throughput on an M-class Mac is ~1–2 sessions/sec for full analysis.
Status: v1.0.1 — stable, daily-driver tested, security-audited (zero critical findings), on PyPI, available as a Claude Code plugin. Validated against 433 real Claude Code sessions across 37 inferred projects (measured 2026-08-12). 546 unit tests passing.
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 model carry more state.
Longhand goes the other direction.The model doesn't need to carry the memory. The disk does.
The "memory crisis" in AI was an artificial constraint. Storage is solved. SQLite is from 2000. ChromaDB is two years old. Both run on a laptop. Longhand bypasses the crisis by ignoring it — your past sessions are already on disk, written by Claude Code itself, in JSONL files that contain every single event verbatim. Longhand reads those files, indexes them locally, and gives you semantic recall over your entire history without ever sending a token through someone else's API.
Storage footprint:~5GB for a heavy power user (430+ sessions, 195k+ events, months of daily Opus usage across 37 inferred projects). Typical users: 200–400MB. Once Claude Code rotates the source files off disk, Longhand isn't a duplicate — it's the only copy.
Python 3.10 – 3.14 are all fully supported and gated in CI— every release must pass the full suite on all five before it can merge.
Longhand pinschromadb<1.0foreveryPython version, not just 3.14. The pin originated with chromadb's newer Rust bindings segfaulting on 3.14 (#4, now closed), and it stays until a 1.x chromadb is verified across the whole matrix.
Windows: CI-tested, best-effort.Awindows-latest × py3.12leg runs on every PR and has gone green on every run since v0.13.0, but it is non-blocking and covers one Python version on GitHub's runners. That is honest evidence, not a support tier — Linux and macOS are the tested platforms. Windows bugs are welcome as issues; they just aren't release-blocking.
Longhand 1.0 makes five promises, each backed by an enforcement artifact in the repo. The full text is inCOMPATIBILITY.md; the short version:
- Stable surface— CLI and MCP frozen through 1.x. Removals only at a major version, and only after warning for one full minor.
- Forward data compat— a database written by 0.11+ opens on any later 1.x. Migrations are automatic, one-time, never renumbered. Older code refuses a newer database loudly rather than operating blind.
- Hook guarantees— hooks never raise, never touch the network, never block your prompt.
- Upstream drift is never silent— unknown transcript entries are preserved, surfaced indoctor, and regression-gated.
- Honest metrics— counts reflect real signals, anddoctornever recommends a remedy that cannot work.
Deprecation policy:anything slated for removal warns for at least one full minor release first, and the warning names its replacement. Retired MCP tool names are the one thing that never goes away — they leave the tool listing but keep answering forever with a migration note, because those names live in users' ownCLAUDE.mdfiles.
The philosophical split:claude-mem asks an AI what was important and keeps that. Longhand keeps the actual bytes and lets you decide later.If you trust a model's judgment about its own past, claude-mem's approach is cheaper at query time (pre-summarized) and easier on storage. If you've ever been burned by a summary that dropped the thing that turned out to matter, Longhand is the tool that never throws anything away.
Both can coexist on the same machine — they operate on the same JSONL files without interfering.
Longhand is built on a handful of principles. If you disagree with them, you probably want a different tool.
1. Information doesn't disappear — it moves.
When data goes "missing" it's almost never actually gone. It got compressed, summarized, filed somewhere else, or renamed. Find the raw source and the truth is still there waiting. Claude Code already writes every session to disk as JSONL. That file is the raw source. Longhand just reads it.
2. Summarization is a lossy decision disguised as a convenience.
Most AI memory systems read a conversation and ask the AI to write down "what mattered." The AI is now the gatekeeper of its own memory, and the AI has incentives — brevity, confidence, coherence — that aren't the same as truth. You end up with a story about what happened instead of what happened.
Longhand never summarizes. It stores the complete record and lets you query it.
3. The raw record is cheap. Acting like it isn't wastes it.
A full Claude Code JSONL file is kilobytes to low megabytes. A year of daily sessions is hundreds of megabytes. That is nothing on modern hardware. There is no engineering reason to throw the data away. Summary-based memory isn't saving space — it's giving away information that was free.
4. The thinking is the most valuable part.
When Claude produces athinkingblock, that's the reasoning behind the decision — usually invisible to the user, almost always more useful than the final answer. Summary-based memory throws thinking blocks away because they're "internal." Longhand treats them as first-class events. "What was I thinking when I chose to use a conditional update?" pulls the verbatim thinking block that contains the answer.
5. A fix you can't reproduce is a fix you didn't keep.
If you fixed a bug in March, the state of that file when the bug was fixed is a fact. Longhand reconstructs it deterministically by applying every edit in sequence from the session JSONL. No guessing, no AI inference, just literal application of the diffs. You can see the exact state of any file at any point in any past session.
6. Memory should be proactive, not just searchable.
A searchable archive is useful but passive. Real memory answers fuzzy questions. "A couple months ago I was building a game that kept breaking, then you fixed it — bring that fix forward." Longhand parses the time phrase, matches the project, finds the problem→fix episode, and returns the diff. You don't have to know the session ID. You just have to remember that it happened.
Everything in Longhand's analysis is rules-based. Regex error detection. Hash-based project IDs. Forward-walking episode extraction. No LLMs in the core pipeline. That means fast (< 200ms recall queries), reproducible (same input → same output), and fully local (no API keys, no cloud). An LLM layer could go on top later, but the foundation runs on laws, not on a model's opinion.
Your Claude Code history is yours. It goes into a SQLite file and a ChromaDB directory in~/.longhand/. No telemetry. No sync. No account. If your laptop is offline, Longhand works. If Anthropic goes down, Longhand works. If you delete the directory, it's gone.
One boring exception, disclosed in full: the interactive CLI checks pypi.org for a newer Longhand version at most once a day. That request carries nothing but itself — no telemetry, no identifiers, nothing about your corpus — and a newer version just shows up as a dim one-line hint and adoctorrow. It never runs from hooks or the MCP server, never blocks a command, andLONGHAND_NO_UPDATE_CHECK=1turns it off entirely. "Zero API calls" means what it always meant: no LLM or cloud service ever touches your data.
When you use Claude Code, every session writes a JSONL file to~/.claude/projects/<project>/<session-id>.jsonl. That file contains every message, every tool call, every thinking block, every file edit with full before/after content, and a millisecond-precise timestamp for each event.
Longhand reads those files. Then it gives you:
- Semantic searchacross every event you've ever generated
- Filterable search— by tool, file, session, project, time range, event type — all filters combinable
- Tool call archaeology— "show me every Bash command I ran in March that touched Supabase"
- File history across sessions— every edit to a specific file, chronologically, across all your sessions
- Session replay— reconstruct any file's state at any point in any past session
- Reasoning retrieval— query Claude's verbatim thinking blocks
- Timeline view— chronological playback with pagination (offset, tail, summary-only scan mode)
- Fuzzy recall— natural-language questions about past work ("that race condition fix from last week")
- Project inference— automatic detection of which projects you've worked on, with categories and aliases
- Episode extraction— automatic detection of problem→fix sequences in your sessions
- Conversation segments— topic-level clustering (stories, design discussions, debugging, planning) so recall finds thewhy, not just thewhat
- Git-aware project recall— ask "where did we leave off on X" and get recent commits, unresolved issues, last session outcome in one call
- Git commit extraction— structured extraction of every git commit, push, merge, checkout from sessions, linked to episodes
- MCP server— 13 tools that let Claude query Longhand directly during live conversations
- Auto-ingest hook— drops into Claude Code'sSessionEndhook so new sessions are indexed automatically
- Live ingestion— optionalStophook tails the active transcript between turns so in-flight sessions show up inrecallimmediately
- Plan history— every Write/Edit to~/.claude/plans/.mdis captured as a first-class entity, queryable vialonghand plans listand thelist_plansMCP tool
- Secret redaction (opt-in)—longhand config --set redact.enabled=truemasks secret-shaped strings (API keys, tokens, JWTs, DB passwords) at ingest before they reach the index;longhand redact --applyretroactively masks data ingested earlier
- Background reconciler— optional launchd job (longhand schedule install-reconciler) keeps the index honest without manualreconcile --fixruns
- Context injection—UserPromptSubmithook auto-injects relevant past context before Claude sees your message (configurable threshold and size cap)
- Configurable—longhand configto tune injection relevance, token budget, and behavior without editing code
That's it.longhand setupbackfills your existing Claude Code history, installs the hooks that keep it updated automatically, registers Longhand as an MCP server for Claude Code, and verifies everything works. About two minutes the first time, zero maintenance after that.
To upgrade later:pip install -U longhand.
git clone https://github.com/Wynelson94/longhand.git cd longhand pip install -e . longhand setup
longhand ingest # ingest all your existing Claude Code history longhand analyze --all # run analysis (projects, outcomes, episodes, segments) longhand hook install # wires both SessionEnd and Stop hooks longhand ingest-live # live-tail the active transcript (Stop hook calls this) longhand prompt-hook install # (optional) auto-inject past context into new prompts longhand mcp install # let Claude Code call Longhand as MCP tools longhand schedule install-reconciler # (optional) launchd job to run reconcile --fix periodically longhand config # view/tune hook behavior (relevance threshold, injection size) longhand doctor # verify everything is wired up
# What's in the archive? longhand stats longhand sessions longhand projects # Daily-use commands — status is the single resume command (git-status shape) longhand status # what have I been up to (recent digest) longhand status --days 30 -p bsoi # filtered digest longhand status <project-name> # where did we leave off on a project (git-aware) longhand status --session <session-id> # pick up where a session left off longhand history src/app/route.ts # every edit ever to a file # (recap / continue / patterns / reanalyze were deprecated aliases through # 0.13 and were removed at 1.0 — use status, recall, and analyze --all) # Semantic search longhand search "race condition" longhand search "stripe webhook" --tool Edit longhand search "why did we" --type assistant_thinking # Proactive recall (the fun one) longhand recall "that clerk type error I fixed a couple weeks ago" longhand recall "the python missing module bug last month" # Session inspection longhand timeline <session-id-prefix> longhand replay <session-id> /path/to/file.ts longhand diff <event-id> # Git history longhand git-log # recent git operations across all sessions longhand git-log <session-id> # git ops in a specific session longhand git-log --type commit # only commits longhand git-log --query "fix parser" # search commit messages # Export longhand export latest-fix # most recent resolved episode longhand export ep_<id> --out fix.md # specific episode to file longhand export <session-id-prefix> # full session timeline # Configuration longhand config # show current hook settings longhand config --set hook.min_relevance=3.0 # tune injection threshold longhand config --set hook.max_inject_chars=1000 # cap token usage # Plans + background maintenance longhand plans list # every plan-mode plan you've written longhand plans list --limit 100 # raise the row cap (default 50) longhand schedule install-reconciler # background launchd job; runs reconcile --fix
Session IDs accept prefix matches —longhand timeline cf86is enough if only one session starts with that.
$ longhand recall "that stripe webhook I was fixing" ╭─ Project matches ───────────────────────────────────────╮ │ new-product (nextjs web app) · alias: 'stripe' · 1.52 │ ╰─────────────────────────────────────────────────────────╯ Found it: new-product · 2 weeks ago · session a4ba29d1 ### What went wrong Type error: Property 'current_period_end' does not exist on type 'Subscription'. ### How it was diagnosed
In Stripe's type definitions, current_period_end moved off the Subscription interface. It's still on the actual API payload but the types don't expose it. We need to cast through Record<string, unknown> to access it.
### The fix Edit on route.ts: 'const periodEnd = sub.current_period_end' → 'const periodEnd = (sub as Stripe.Subscription & Record<string, any>).current_period_end as number' Diff: - const periodEnd = sub.current_period_end + const periodEnd = (sub as Stripe.Subscription & Record<string, any>).current_period_end as number ✓ Verified — a test passed after the fix. Other candidates (4) • 2 weeks ago: Type error: Module '"@/lib/utils"' has no exported member 'getInitials'. • 2 weeks ago: Type error: Property 'role' does not exist on type 'User'.
That's one local command. No API call. The fix came from a session file Claude Code wrote to your disk weeks ago and Longhand had been waiting with the answer the whole time.
Runlonghand mcp installto wire Longhand into Claude Desktop's config. After you restart Claude Desktop, it has thirteen tools:
- search— semantic search with session, project, tool, file, and event_type filters (all combinable); passcontext_eventswith asession_idto get each match wrapped in its surrounding conversation
- list_sessions— recent sessions with project/time filters; passproject_id(plus optionalsince/until) for a project's outcome-enriched session timeline
- get_session_timeline— chronological view with offset/tail pagination and summary-only scan mode (tail: Ncovers "the latest events / how did it end")
- replay_file— reconstruct file state at a point in time
- get_file_history— every edit to a file across all sessions
- get_stats— storage statistics
- recall— fuzzy natural-language recall (use this first): a narrative built from conversation segments and session timelines, with high-precision problem→fix episodes when the work left clean evidence
- recall_project_status— "where did we leave off on X?" — git-aware project summary with commits, issues, last outcome
- find_episodes— structured search for problem→fix pairs; passepisode_idfor full detail on one episode (referenced events, diff, post-fix file state)
- list_projects— browse inferred projects; passmatchfor fuzzy candidates with scored reasons
- list_plans— every Write/Edit to~/.claude/plans/.mdacross your entire history
- find_commits— search across all sessions by commit message, hash prefix, or branch name; or pass asession_idwithout a query for one session's chronological git story
- reconcile— wrapslonghand reconcileso Claude can re-attribute and re-ingest from inside a session after a staleness banner; passfixexplicitly (the implicit default flips to dry-run at v1.0)
Deprecated (still answer through 0.x, with a migration preamble; leave the listing at v1.0):search_in_context→search(context_events)·get_latest_events→get_session_timeline(tail)·get_project_timeline→list_sessions(project_id)·get_session_commits→find_commits(session_id)·get_episode→find_episodes(episode_id)·match_project→list_projects(match)
All tools supportmax_charsoutput capping with pagination hints. No more 96k dumps crashing your context.
Once installed, you can ask Claude things like"what did we decide about the auth middleware in last week's session?"*and it will actually search its own past work.
longhand hook installadds two hooks to~/.claude/settings.json—Stopfor live tailing between turns,SessionEndfor the full analysis pass at session close:
{ "hooks": { "Stop": [ {"command": "longhand ingest-live"} ], "SessionEnd": [ {"command": "longhand ingest-session"} ] } }
Both commands readtranscript_pathfrom the hook's stdin JSON, so no flags are needed in the hook entry itself.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
