Longhand

Longhand

[](https://glama.ai/mcp/servers/Wynelson94/longhand) [](https://pypi.org/project/longhand/)

[](https://safeskill.dev/scan/wynelson94-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](#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.1 — 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.

---

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 model carry more state.

Longhand goes the other direction. The model doesn't need to carry the memory. The disk does.

| | Bigger context windows | Longhand | |----------------------|----------------------------------------------|-----------------------------------| | Where it lives | Rented from a model provider | A SQLite file + ChromaDB on your laptop | | Cost per query | Tokens × dollars | Zero | | Privacy | Goes through someone else's servers | Never leaves your machine | | Speed | Seconds to minutes for large contexts | ~56ms search · ~1.4s full recall | | Loss | Attention degrades in the middle of long contexts | Every event from the source file, nothing dropped | | Persistence | Dies when the window closes | Lives until you delete the file | | Across model versions | Doesn't transfer | Same data, any model | | Offline | No | Yes | | Scales with | Provider's pricing | Your hard drive |

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.

Local. Complete. Yours.

> Storage footprint: ~2GB for a heavy power user (240+ sessions, 125k events, months of daily Opus usage across 14 repos). Typical users: 200–400MB. Once Claude Code rotates the source files off disk, Longhand isn't a duplicate — it's the only copy.

---

Python version note

Python 3.10 – 3.13 are fully supported. On Python 3.14, longhand pins chromadb/.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 search across 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 the why, not just the what
• 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 — 19 tools that let Claude query Longhand directly during live conversations
• Auto-ingest hook — drops into Claude Code's SessionEnd hook so new sessions are indexed automatically
• Live ingestion — optional Stop hook tails the active transcript between turns so in-flight sessions show up in recall immediately
• Plan history — every Write/Edit to ~/.claude/plans/*.md is captured as a first-class entity, queryable via longhand plans list and the list_plans MCP tool
• Secret redaction (opt-in) — longhand config --set redact.enabled=true masks secret-shaped strings (API keys, tokens, JWTs, DB passwords) at ingest before they reach the index; longhand redact --apply retroactively masks data ingested earlier
• Background reconciler — optional launchd job (longhand schedule install-reconciler) keeps the index honest without manual reconcile --fix runs
• Context injection — UserPromptSubmit hook auto-injects relevant past context before Claude sees your message (configurable threshold and size cap)
• Configurable — longhand config to tune injection relevance, token budget, and behavior without editing code

---

Install

pip install longhand
longhand setup

That's it. longhand setup backfills 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.

Developer install (from source)

git clone https://github.com/Wynelson94/longhand.git
cd longhand
pip install -e .
longhand setup

Or run the individual commands yourself

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

---

Quick Start

# What's in the archive?
longhand stats
longhand sessions
longhand projects

# Daily-use commands
longhand recap                              # what have I been up to
longhand recap --days 30 --project bsoi     # filtered recap
longhand continue               # pick up where I left off (session-scoped)
longhand status               # where did we leave off on a project (git-aware)
longhand patterns                           # what bugs do I keep fixing
longhand history src/app/route.ts           # every edit ever to a file

# 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 
longhand replay  /path/to/file.ts
longhand diff 

# Git history
longhand git-log                            # recent git operations across all sessions
longhand git-log                # 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_ --out fix.md        # specific episode to file
longhand export          # 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 cf86 is enough if only one session starts with that.

---

Recall Example

$ 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, currentperiodend 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 to access it.

### The fix
Edit on route.ts: 'const periodEnd = sub.current_period_end' → 'const periodEnd
= (sub as Stripe.Subscription & Record).current_period_end as number'

Diff:
- const periodEnd = sub.current_period_end
+ const periodEnd = (sub as Stripe.Subscription & Record).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:

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Wynelson94](https://github.com/Wynelson94)
- **Source:** [Wynelson94/longhand](https://github.com/Wynelson94/longhand)
- **License:** MIT
- **Homepage:** https://glama.ai/mcp/servers/Wynelson94/longhand

Install and usage instructions live in the source repository linked above.