Longhand

Longhand

Codex もお使いですか？ Claude Code と Codex で 1 つのメモリアーカイブを共有する。

Claude Code 向けの永続的なローカルメモリです。 あらゆる Claude Code セッションのすべてのツール呼び出し、ファイル編集、思考ブロックを、ありのままにあなたのマシンへ保存します。あいまいな自然言語で質問して検索、再生、呼び出しができます。API 呼び出しはゼロ。要約はゼロ。何を記憶する価値があるかを AI が判断することもありません。

Claude Code は数週間後、セッションファイルをひっそりとローテーションします。 Longhand はファイルがなくなる前に SQLite へ取り込みます。いったん取り込めば、元の JSONL ファイルが削除された後も履歴は永久に残ります。早めにインストールしてください。保存しなかった過去は取り戻せません。

~/.claude/projects/ に Claude Code のセッションが 20 件以上ある場合、Longhand は API 呼び出しを一切せず、これまでのあらゆる修正、決定、会話を約 29 ms で横断検索できます。

トークンを大量に使いますか？ いいえ。最もよく使うツールは、設計上出力に上限を設けています。 100 件以上のセッションを横断する recall の結果は約 4K トークンです。生のセッション JSONL を 1 つ読む場合、その 10～50 倍のコストがかかります。出力に上限があるツールとないツールについては、トークン予算をご覧ください。

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

まず試してみたいですか？ longhand demo を実行すると、架空の 3 セッションのサンプルコーパスを使った 60 秒のウォークスルーを利用できます。実際の ~/.claude と ~/.longhand には触れません。デモでは、Stripe webhook のバグ、Supabase 認証の移行、その後の 401 修正を含むサンドボックス化されたストアを用意し、セッション横断の recall とプロジェクトステータスを実行します。導入を決める前に、出力を確認できます。

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

1.0.0 にアップグレードしますか？ このリリースで、0.13 から始まった非推奨期間が終了します。ここで削除された機能は、すべて 0.13.0 以降、警告が表示されていました。

• 4 つの CLI エイリアスを削除しました：patterns → recall "<topic>"、recap → status --days N、continue → status --session <prefix>、reanalyze → analyze --all。
• reconcile MCP ツールの既定の動作がドライランになりました。 暗黙的な修復に依存するエージェントループをお使いの場合は、fix=true を明示的に指定してください。ドライランであることはペイロードに示されます。
• 6 つの廃止済み MCP ツールが一覧から削除されました（19 → 13）が、移行案内を返す動作は今後も継続します。廃止された名前はユーザー自身の CLAUDE.md ファイルに残っているため、決してハードエラーにしてはいけません。
• 新規：COMPATIBILITY.md に、1.x が保証することと保証しないことを記載しています。

データベースへの対応は不要です。マイグレーションは自動で行われ、0.11 以降のストアは、それ以降のどの 1.x でも開けます。これが約束 2 であり、テストスイートにはそれを証明する実際の 0.11 スキーマのフィクスチャがあります。

1.2.x にアップグレードしますか？ 削除された機能はありませんが、知っておくと役立つ修正があります。

• 1.2.3: MCP の get_session_timeline で、5,000 件を超えるイベントがあるセッションの tail が、正しい直近 N 件のイベントを返すようになりました。以前は途中のイベントを返していました。setup の最後のヒントでは、1.0 で削除された recap の提案をやめ、status --days 7 を提案するようになりました。Recall のフッターと get_session_timeline 自身のツール説明では、search_in_context（1.0 でツール一覧から削除されましたが、引き続き応答します）への言及をやめ、search を案内するようになりました。フッターには呼び出し方法も明記されています。search(session_id=…, query=…, context_events=5)
• 1.2.2: recall は、最上位の検索結果が他の候補よりかなり古い場合に、その旨を示すようになりました。古い修正が現在も有効であるかのように見えることを防ぎます（Recall Example を参照）。Codex のコンテキスト圧縮レコード（compacted）によって、doctor のトランスクリプト形式の不整合に関する警告が誤って表示されることはなくなりました。
• 1.2.1: MCP の get_session_timeline にあったセンチネルのバグにより、tail を明示的に渡さない限り、limit／offset が無視され、すべての呼び出しでイベントが常に 1 件だけ返されていました。この問題を修正しました。search のプロジェクト自動スコープ設定が、明示的な session_id を上書きすることもなくなりました。

0.13.0 にアップグレードしますか？ 互換性に影響する変更はありません。このリリースで v1.0 の非推奨期間が始まり、以前の名前はすべて、置き換え先を案内しながら引き続き動作していました。

• status が再開用の唯一のコマンドになりました。引数なしの status は最近のダイジェスト（以前の recap）、status <project> は変更なし、status --session <prefix> はセッション末尾（以前の continue）を表示します。以前のコマンドも引き続き実行できますが、置き換え先が表示されます。v1.0 で削除されます。
• 6 つの MCP ツールが、同じパラメーターを持つ 6 つの後継ツールに統合されました（search_in_context → search + context_events、get_episode → find_episodes + episode_id など。完全な一覧は CHANGELOG を参照してください）。廃止された名前も、移行に関する注記を先頭に付けて引き続き応答します。
• フックはゼロ以外の終了コードを返さなくなりました。失敗は ~/.longhand/logs/ に記録され、新しい doctor の 2 行（Hook errors、Transcript format）で確認できます。
• 「今日」／「昨日」の Recall 対象期間は、UTC ではなくローカルの暦日に従うようになりました。UTC 以外の地域では、ランキングが一度変わる場合があります。
• Windows ユーザー向け：このリリースでは、取り込みロックの生存確認によって他の longhand プロセスが終了する重大なバグを修正しました。
• 新機能：LONGHAND_DATA_DIR を使うと、CLI、フック、MCP サーバーのストアをまとめて移動できます。ただし、longhand config --set は、ストアの移動先に関係なく常に ~/.longhand/config.json に書き込みます（#96。--edit は現在何も行いません。同じ問題です）。スクリプトから使える status --json／doctor --json も追加されました。

0.9.0 にアップグレードしますか？ 実行中のセッションを取り込めるようになり、プランの履歴が第一級のデータとして保持され、任意の調整ジョブによってバックグラウンドでインデックスの整合性を保てるようになりました。

• 新しい longhand ingest-live コマンドは、Claude Code の Stop フックから実行され、アシスタントのターン間にアクティブなトランスクリプトを追跡します。進行中のセッションは、list_sessions、get_session_timeline／timeline、get_file_history、replay_file からすぐに検索できるようになります。書き込むのはイベントのみで、埋め込みは作成しません。そのため、recall とセマンティック検索の search で確認するには、SessionEnd の処理、または分析を伴って再取り込みする reconcile --fix の処理が必要です。
• 新しい longhand plans list コマンドと list_plans MCP ツールを追加しました。これにより、全履歴から ~/.claude/plans/*.md に対するすべての Write／Edit が表示されます。プランはエピソードと並ぶ独立したエンティティとして抽出されるようになりました。
• 新しい longhand schedule install-reconciler は、定期的に reconcile --fix を実行する任意の launchd ジョブをインストールします。ライブフックやセッション終了後のフックで見逃したものを、自分で気にかけなくても検出できます。
• Stop フックは、既存の SessionEnd フックと併用できます。ライブフックはトランスクリプトの増加を追跡し、SessionEnd フックはセッション終了時に完全な分析処理を行います。

0.8.1 にアップグレードしますか？ 古さを示すシグナルが適切な場所すべてに反映されるようになり、reconcile が MCP ツールになりました。Claude はセッション内からインデックスを自動修復できます。

• search と list_sessions は、対象プロジェクトに未取り込みのディスク上のトランスクリプトがある場合、stale: true と stale_reason を付けてレスポンスを返すようになりました。v0.8.1 より前は、きれいに見える空の結果を返していました（recall_project_status が検出するように作られたのと同じサイレント障害の形ですが、1 層上で発生していました）。
• 新しい reconcile MCP ツールは、longhand reconcile --fix を実行します。古さを知らせるバナーが表示された後、Claude はユーザーに CLI コマンドの実行を求める代わりに、直接 reconcile を呼び出します。
• list_sessions のデフォルトの limit を20から50に引き上げました。アクティブな日には、5つ以上のプロジェクトで5つ以上のセッションにまたがることが日常的にあります。以前のデフォルトでは、レビューが気付かないうちに切り詰められていました。

0.7.x 以前からアップグレードしますか？ より明瞭なリコールのナラティブと、その下支えとなる実際のバグ検出テスト層が追加されました（0.8.0 より）：

• v0.8 より前の _compose_fix_summary は、抽出されたエピソードの半数（参照コーパスの49％）に、文字列 "Intent:" のラベルを先頭に追加していました。このラベルは、それらのエピソードのすべてのリコールナラティブに漏れていました。移行 v4 により、ストアを初めて開いたときに既存の行からこのラベルが削除されます — コマンドは不要です。
• fix_summary の差分コンテンツは、トークンの途中（phoneNum'、family?:'、strin'）で切れるのではなく、空白の境界で切り詰められ、目に見える … が付くようになりました。今後のデータのみが対象です。
• ナラティブのフッターにある「その他の一致」行に、セッション ID が含まれるようになり、詳細を確認できます。
• 新しいカナリアハーネス（tests/fixtures/corpus/）により、実際にリリースされたバグに回帰テストを固定できるようになりました。新しいリコールバリデーター（scripts/recall_diff.py）は、ライブコーパスに対するランキング結果のスナップショットを作成して差分を確認し、pytest では検出できない回帰を見つけます。

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

0.5.x からもアップグレードする場合は、v0.6 の推論改善に基づいて複数プロジェクトのセッションを再帰属するため、longhand reconcile --fix を一度実行してください（プロジェクト内に cd して開始したセッションは、最初のイベント時の cwd ではなく、作業の大半が行われたプロジェクトに帰属するようになりました）。0.5.8 以前をお使いの場合は、次のように続けて実行してください：longhand reconcile --fix && longhand analyze --all。どちらも冪等です。

大規模な履歴がありますか？（~/.claude/projects が1 GBを超える場合） 初回のバックフィルには、MクラスのMacで10～30分かかる見込みです。所要時間の大半は、すべてのコアで埋め込みモデルを実行する時間です（そのためCPU使用率が3桁になることがあります。ハングではなく、ONNX が正常に動作している状態です）。--skip-analysis は、イベントの埋め込みではなく、エピソード／セグメントの抽出とプロジェクト／セッションレベルのベクトルというもう一方の処理を後回しにします。イベントの埋め込みは常に実行されるため、時間は多少短縮されますが、主要なコストは削減されません：

longhand setup --skip-analysis   # events stored + embedded; episodes/segments deferred
longhand analyze --all           # fill in episodes + segments + project/session vectors whenever, safe to background

このフラグに関係なくすべてのイベントが埋め込まれるため、--skip-analysis の後すぐに search、タイムライン、ファイル履歴、コミット検索を利用できます。recall のエピソード／セグメントのナラティブと recall_project_status では、参照するデータを用意するために analyze --all の実行が必要です。MクラスのMacでの全分析の一般的な処理速度は、毎秒約1～2セッションです。

ステータス：v1.2.3 — 安定版、日常利用でテスト済み、セキュリティ監査済み（重大な指摘ゼロ）、PyPI で公開中、Claude Code プラグインとして利用可能です。45の推定プロジェクトにわたる実際の792セッション（Claude Code 786件、Codex 6件）で検証済みです（2026-09-27 測定）。ユニットテスト617件が合格しています。

ドキュメント全文： Longhand Wiki — はじめに、CLI リファレンス、MCP ツールリファレンス、アーキテクチャ、トラブルシューティング。

逆転の発想

誰もがコンテキストウィンドウを大きくして、AI のメモリ問題を解決しようとしています。100 万トークン。200 万トークン。無限のコンテキスト。業界全体が同じ方向に向かって競争しています。モデルがより多くの状態を保持できるようにするのです。

Longhand は逆の方向を目指します。モデルがメモリを保持する必要はありません。ディスクが保持すればよいのです。

† Claude Code の 9 種類のエントリータイプ（KNOWN_SKIP_ENTRY_TYPES）と、Codex 側の 3 種類のトップレベルレコードタイプ（CODEX_SKIP_RECORD_TYPES）に加え、10 種類の event_msg（CODEX_SKIP_EVENT_MSG_TYPES：正規メッセージの UI 側のミラーと、ターン管理情報）は、主にハーネスの純粋な管理情報（キューマーカー、進捗通知、使用状況や状態のスナップショット）であり、保存せずに認識してスキップします。ただし、「コンテンツが一切破棄されない」というわけではありません。これらのタイプのうち attachment は、独自の attachment.prompt フィールドにキューに入った後続のプロンプトを含む場合があり、Codex の暗号化された推論レコードとコンテキスト圧縮（compacted）レコードは完全に破棄されます。それ以外の実際のコンテンツを含むもの — 通常のメッセージ、ツール呼び出し、ファイル編集、思考ブロックのすべて — はそのまま保持されます。

AI の「メモリ危機」は、人為的に作られた制約でした。ストレージの問題は解決済みです。SQLite は 2000 年から存在し、ChromaDB は成熟したオープンソースのベクトルストアです。どちらもノート PC 上で動作します。Longhand は危機を無視することで、その危機を回避します。過去のセッションはすでにディスク上にあり、Claude Code 自身が、あらゆるイベントを一つ残らずそのまま記録した JSONL ファイルに書き込んでいます。Longhand はそれらのファイルを読み込み、ローカルでインデックスを作成し、他者の API にトークンを送信することなく、履歴全体を意味的に呼び出せるようにします。

ローカルに。完全に。あなたのもの。

ストレージ使用量： ヘビーユーザーの場合、約 7.5GB（792 以上のセッション、269,000 以上のイベント、推定 45 プロジェクトにわたる数か月間の Claude Code 毎日利用 — 2026-09-27 に計測。［統計］(#stats)を参照）。一般的なユーザーの場合：200～400MB。Claude Code が元ファイルをディスクからローテーションで削除すると、Longhand は重複ではなく唯一のコピーになります。

プラットフォームのサポート

Python 3.10～3.14はすべて完全にサポートされ、CIで必須チェックの対象です — ブランチ保護により、PRのマージ前に5つすべてのバージョンで全テストスイートが成功する必要があります（管理者はこのチェックを回避できます。CONTRIBUTING.mdをご覧ください）。

Longhandでは、Pythonのバージョンにかかわらず、すべての環境でchromadb<1.0を固定しています。これは、chromadbの新しいRustバインディングが3.14でセグメンテーション違反を起こしたことから始まり（#4、現在はクローズ済み）、1.xのchromadbがマトリックス全体で動作することを確認できるまで継続します。

Windowsはサポートされていません。WSL2を使用してください。 すべてのPRでwindows-latest × py3.12のジョブが実行されますが、これはブロックしないcontinue-on-errorステップであり、失敗します。実行のたびに12件のコアテストが失敗します（フックのインストール／アンインストールの冪等性、設定ファイルのパス、レダクション、ライブ取り込みの行数カウント、デモのクリーンアップなど。詳細は#112で追跡しています）。不安定なエッジケースではありません。continue-on-errorが失敗したステップを無視するため、GitHubのUIではジョブが緑色で表示されますが、これは証拠収集を目的としたものであり、Longhandがそこで動作するという主張ではありません。CIで実際に必須チェックの対象となるプラットフォームはLinux（3.10～3.14）のみで、macOSのジョブはありません。macOSは作者が日常的に使うOSで、手動で動作確認している環境ですが（Statsをご覧ください）、CIで独立して検証されているわけではありません。

CIのマトリックスにかかわらず、macOS固有の機能が2つあります。schedule install-reconcilerはlaunchdジョブをインストールし、それ以外の環境では何もしません（Linuxではcron／systemd-userを使用し、WindowsではWSL2を使用してください）。mcp installもClaude DesktopのmacOS設定パスにしか書き込みません（#105）。Linux向けのClaude Desktopリリースはなく、Windowsもサポートされていません（#112）。Windows版Claude DesktopをWSL2上のインストールに接続するには、wsl.exeを通じてLonghandを起動するよう設定を手動で編集する必要がありますが、これはテストされていません。

Codex DesktopとCodex CLIのスレッドは1.1.0から同じアーカイブに保存されます。Codexとの連携をご覧ください。

互換性

Longhand 1.0では5つの約束を掲げており、それぞれリポジトリ内の成果物によって遵守が確認されます。全文は**COMPATIBILITY.md**に記載されています。要約は次のとおりです。

1. 安定したインターフェース — CLIとMCPは1.xを通じて凍結されます。削除はメジャーバージョンの更新時に限り、かつ1つのマイナーバージョン全体を通じて警告した後にのみ行います。
2. 前方データ互換性 — 0.11以降で書き込まれたデータベースは、それ以降の1.xで開けます。マイグレーションは自動で一度だけ実行され、番号が変更されることはありません。古いコードは、新しいデータベースを知らないまま操作するのではなく、その旨を明確に示して処理を拒否します。
3. フックの保証 — フックは例外を発生させず、ネットワークに接続せず、プロンプトをブロックしません。
4. 上流の変更を黙って見過ごさない — 未知のトランスクリプト項目は保持され、doctorで表示され、回帰テストの必須チェック対象となります。
5. 誠実なメトリクス — カウントは実際のシグナルを反映し、doctorが実行できない対処法を推奨することはありません。

非推奨化ポリシー： 削除が予定されているものには、少なくとも1つのマイナーバージョン全体を通じて事前に警告し、その警告には代替手段を明記します。廃止されたMCPツール名だけは、決してなくなりません。ツール一覧からは削除されますが、ユーザー自身のCLAUDE.mdファイルに名前が記載されているため、移行に関する注記を返し続けます。

Longhand と claude-mem の比較

thedotmack/claude-mem は、GitHub で最も人気のある Claude Code 向けメモリーツールです（スター数 55k 以上）。優れたツールです。一方で、Longhand とは正反対の方法でメモリーの問題を解決しようとしています。どちらを選ぶか決める前に、その違いを理解しておく価値があります。

根本的な考え方の違いはこうです。claude-mem は AI に何が重要だったかを尋ね、それを保存します。Longhand は実際のバイト列を保存し、後から判断できるようにします。 モデルが自らの過去について下す判断を信頼するなら、claude-mem の方法は事前に要約されているため、クエリ時のコストが低く、ストレージの負担も軽くなります。重要だと後から分かったことが要約から抜け落ちていて、困った経験があるなら、何も捨てない Longhand が適しています。

どちらも同じマシン上で併用できます。同じ JSONL ファイルを使いますが、互いに干渉しません。

原則

Longhand はいくつかの原則に基づいて作られています。これらに同意できない場合は、別のツールを選ぶほうがよいでしょう。

1. 情報は消えるのではなく、移動します。

データが「見つからなくなった」とき、実際に消えていることはほとんどありません。圧縮、要約、別の場所への格納、または名称の変更が行われただけです。生の情報源を見つければ、真実はそこに残っています。Claude Code はすでに、すべてのセッションを JSONL としてディスクに書き込んでいます。そのファイルが生の情報源です。Longhand はそれを読み取るだけです。

2. 要約は、利便性を装った、情報を失う判断です。

多くの AI メモリーシステムは会話を読み込み、AI に「何が重要だったか」を書き出すよう求めます。AI は自らの記憶を管理する門番となり、簡潔さ、自信、一貫性といった、真実とは異なる優先事項を持っています。その結果、実際に何が起きたかではなく、何が起きたかについての物語が残ります。

Longhand は決して要約しません。記録全体を保存し、クエリできるようにします。

3. 生の記録は低コストです。そうでないかのように扱うのは、その価値を無駄にします。

Claude Code の JSONL ファイル全体でも、数キロバイトから数メガバイト程度です。毎日のセッションを 1 年分保存しても、数百メガバイトです。現代のハードウェアでは取るに足らない量です。データを捨てる工学的な理由はありません。要約ベースのメモリーは容量を節約しているのではありません。無料で保持できる情報を手放しているのです。

4. 最も価値があるのは思考です。

Claude が thinking ブロックを生成するとき、そこには判断の根拠となる推論が含まれています。通常、ユーザーからは見えませんが、ほとんどの場合、最終回答よりも役に立ちます。要約ベースのメモリーは、思考ブロックが「内部情報」だからという理由で捨てます。Longhand は思考ブロックを第一級のイベントとして扱います。「条件付き更新を使うと決めたとき、何を考えていたか」と尋ねれば、答えを含む思考ブロックが逐語的に取得されます。

5. 再現できない修正は、残していないのと同じです。

3月にバグを修正したなら、修正した時点でのそのファイルの状態は事実です。Longhand はセッション JSONL からすべての編集を順番に適用することで、その状態を決定論的に再構築します。推測も、AI による推論もなく、差分をそのまま適用するだけです。過去のどのセッションでも、任意の時点における任意のファイルの正確な状態を確認できます。

6. メモリは検索可能なだけでなく、先回りして役立つべきです。

検索可能なアーカイブは便利ですが、受け身です。本当のメモリは、曖昧な質問にも答えます。「数か月前、よく壊れるゲームを作っていて、あなたが修正してくれたよね。その修正を今の作業にも使って」。Longhand は時間に関する表現を解析し、プロジェクトを照合して、問題から修正に至る一連の出来事を見つけ、差分を返します。セッション ID を知っている必要はありません。そういうことがあったと覚えているだけで十分です。

7. 賢さよりも決定論を優先します。

Longhand の分析はすべてルールベースです。正規表現によるエラー検出。ハッシュベースのプロジェクト ID。順方向にたどるエピソード抽出。コアパイプラインに LLM はありません。そのため高速（ウォーム状態の再呼び出しの中央値は約128ms — 2026-09-27に計測。［統計］(#stats)を参照）、再現可能（同じ入力 → 同じ出力）、そして完全にローカル（API キーもクラウドも不要）です。後から LLM レイヤーを追加することもできますが、基盤はモデルの意見ではなく、ルールに基づいて動作します。

8. ローカルでなければ意味がありません。

Claude Code の履歴はあなた自身のものです。~/.longhand/ 内の SQLite ファイルと ChromaDB ディレクトリに保存されます。テレメトリなし。同期なし。アカウントなし。ノート PC がオフラインでも Longhand は動作します。Anthropic が停止しても Longhand は動作します。ディレクトリを削除すれば、データは消えます。

例外がひとつだけあります。隠さずすべて説明します。インタラクティブ CLI は pypi.org を確認し、新しいバージョンの Longhand があるか調べます。ほとんどのコマンドは24時間のキャッシュを使い、ヒントはコマンドの出力後にのみ表示するため、待っている処理が遅れることはありません。例外は doctor（および doctor を実行する setup）で、テーブルの表示前に毎回、タイムアウト2秒で同期的に最新情報を取得します。このリクエストが送信するのはリクエスト自体だけです。テレメトリも識別情報も、コーパスに関する情報もありません。Claude Code のフックと、Claude Desktop 用に mcp install が実際に設定する mcp-server エントリーポイントでは、この確認は除外されています。ただし、まだ longhand shared-mcp、mcp serve、demo では除外されていません。現在、これらはほかのコマンドと同様、終了時に同じ確認を実行します（#101）。LONGHAND_NO_UPDATE_CHECK=1 を設定すると、すべての確認が無効になります。「API 呼び出しゼロ」の意味は従来どおりです。LLM やクラウドサービスがあなたのデータに触れることはありません。

実際の動作

Claude Code を使用すると、各セッションで ~/.claude/projects/<project>/<session-id>.jsonl に JSONL ファイルが書き込まれます。このファイルには、すべてのメッセージ、すべてのツール呼び出し、すべての思考ブロック、変更前後の内容を含むすべてのファイル編集と、各イベントのミリ秒単位のタイムスタンプが記録されます。

Longhand はこれらのファイルを読み込み、次の機能を提供します。

• セマンティック検索 — これまでに生成したすべてのイベントを対象に検索します
• フィルタ可能な検索 — ツール、ファイル、セッション、プロジェクト、イベントタイプで絞り込みます。すべてのフィルターを組み合わせられます（MCP の search ではすべて使用できます。CLI の search コマンドではツール、ファイル、セッション、タイプを使用できますが、プロジェクトのフィルターはありません。また、どちらにも時間範囲のフィルターはありません）
• ツール呼び出しの調査 — 「Supabase に触れた Bash コマンドを表示」のように検索できます。すべての一致を文字どおり表示するのではなく、関連性順に表示します。ノイズを減らすには、セッションまたはプロジェクトを対象にします
• セッションをまたいだファイル履歴 — すべてのセッションにわたる特定ファイルへの編集を、時系列順に表示します
• セッションのリプレイ — 過去の任意のセッションの任意の時点におけるファイルの状態を再構成します
• 推論の取得 — Claude の思考ブロックをそのまま検索します
• タイムライン表示 — ページネーション付きで時系列再生します（offset、tail、要約のみのスキャンモード）
• あいまい検索 — 過去の作業について自然言語で質問できます（「先週のあの競合状態の修正」など）
• プロジェクトの推定 — 作業したプロジェクトをカテゴリと別名とともに自動検出します
• エピソードの抽出 — セッション内の問題→修正の流れを自動検出します
• 会話セグメント — トピック単位のクラスタリング（ストーリー、設計の議論、デバッグ、計画）により、「何をしたか」だけでなく「なぜそうしたか」も検索できます
• Git を考慮したプロジェクトの情報取得 — 「X の作業をどこまで進めたか」と尋ねると、最近のコミット、未解決の問題、最後のセッションの結果を一度の呼び出しで取得できます
• Git コミットの抽出 — セッションからすべての git commit、push、merge、checkout を構造化して抽出し、エピソードに関連付けます
• MCP サーバー — Claude がライブ会話中に Longhand へ直接問い合わせるための 13 個のツールを提供します
• 自動取り込みフック — Claude Code の SessionEnd フックに組み込み、新しいセッションを自動的にインデックス化します
• ライブ取り込み — hook install で SessionEnd とともにインストールされる Stop フック（個別にはオプション化できません）が、ターン間でアクティブなトランスクリプトを追跡するため、進行中のセッションを list_sessions、タイムライン、ファイル履歴、リプレイからすぐに参照できます。保存するのはイベントのみで、埋め込みは保存しません。セマンティックな recall／search は SessionEnd の処理、または取り込み対象として検出するための reconcile --fix の処理が完了するまで利用できません（ライブ追跡では project_id が設定されないため、reconcile は完全な再取り込みが必要と判断します）
• プラン履歴 — ~/.claude/plans/*.md へのすべての Write／Edit を第一級のエンティティとして記録し、longhand plans list と MCP ツール list_plans から検索できます
• シークレットのマスキング（オプトイン） — longhand config --set redact.enabled=true を設定すると、インデックスに取り込まれる前に、シークレットに見える文字列（API キー、トークン、JWT、DB パスワード）をマスキングします。longhand redact --apply を実行すると、以前に取り込んだデータも遡ってマスキングされます（git コミットメッセージの対象範囲に関する現在の制限については、SECURITY.md と #110 を参照してください）
• バックグラウンドのリコンサイラー — オプションの launchd ジョブ（longhand schedule install-reconciler）により、手動で reconcile --fix を実行しなくてもインデックスを最新の状態に保ちます
• コンテキストの注入 — UserPromptSubmit フックが、Claude にメッセージが届く前に関連する過去のコンテキストを自動注入します（しきい値とサイズ上限を設定可能）。注入されたコンテキストが古く、新しい作業と比べて古びて見える場合は、recall と同じ経過時間に関する Note: … の行を表示します
• 設定可能 — longhand config を使って、コードを編集せずに注入の関連度、トークン予算、動作を調整できます

インストール

pip install longhand
longhand setup

これで完了です。longhand setup は既存の Claude Code の履歴を遡って取り込み、自動更新を続けるフックをインストールし、Longhand を Claude Desktop の MCP サーバーとして登録し、Claude Code に追加するための1行のコマンド（claude mcp add longhand -s user -- longhand mcp-server）を表示して、すべてが動作することを確認します。初回は約2分かかりますが、その後のメンテナンスは不要です。

後でアップグレードするには、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 (installed together)
longhand prompt-hook install          # (optional) auto-inject past context into new prompts
longhand mcp install                  # register Longhand as an MCP server for Claude Desktop
claude mcp add longhand -s user -- longhand mcp-server  # ...and for Claude Code
longhand schedule install-reconciler  # (optional, macOS-only) 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 (macOS); runs reconcile --fix
longhand reattribute                        # dry-run: find sessions attributed to the wrong project
longhand reattribute --fix                  # apply the moves (idempotent)
longhand db vacuum --prune-aux              # reclaim disk space; --prune-aux deletes ALL event_type='unknown' rows —
                                             #   not just harness noise, but doctor's drift records and the deliberately
                                             #   preserved summary/pr-link/worktree-state/frame-link rows too

セッション ID は前方一致を受け付けます。該当するセッションが1つだけなら、longhand timeline cf86 で十分です。

想起の例

$ longhand recall "that stripe webhook I was fixing"

╭─ Project matches ───────────────────────────────────────╮
│ new-product (nextjs web app) · alias: 'stripe' · 1.52   │
╰─────────────────────────────────────────────────────────╯

You asked: that stripe webhook I was fixing

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

Stripe の型定義では、current_period_end は Subscription インターフェースから移動しています。実際の API ペイロードにはまだありますが、型定義には公開されていません。アクセスするには Record<string, unknown> を経由してキャストする必要があります。

### 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 or command succeeded 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'.

これはローカルで実行する1つのコマンドです。API 呼び出しはありません。この修正は、数週間前に Claude Code がディスクに書き込んだセッションファイルから得られたもので、Longhand はずっと答えを用意していました。

上記に示していない点が2つあります。1つ目に、経過時間の警告は、最上位の一致が少なくとも30日前のもので、かつ次点の最新候補より少なくとも30日古く、クエリに時間を示す語句がない場合にのみ表示されます。単に「何週間も古い」というだけでは表示されません。警告が表示されると、「Found it:」の直後に次の行が追加されます。他の一致より古い候補です。最も一致する候補は6か月前のものですが、2か月前の関連作業もあります。現在の作業を指している場合は、「今週」や「今月」のような時間を示す語句を追加してください。 順位付けは変わりません。これは並べ替えではなく警告です。2つ目に、候補が整理されたエピソードではなく会話セグメントから得られた場合、フッターには実際のセッション ID を埋め込んだ正確な追加呼び出しが示されます。search(session_id="a4ba29d1", query="...", context_events=5)。より弱い「関連する可能性があります」フッター（他のセッションにセグメントがある場合に episodes-recall が表示するもの）では、現在、同じ呼び出し形式が文字列の session_id="<session>" プレースホルダー付きで表示されます。実際の ID は、その上の箇条書きからコピーしてください。

MCP 統合

Longhand の13個のツールは、クライアントに関係なく同じです。サーバーの登録方法はクライアントごとに異なります。

Claude Code：

claude mcp add longhand -s user -- longhand mcp-server

または、Claude Code プラグインをインストールしてください（このリポジトリの .claude-plugin/plugin.json と、サーバーを自動登録する同梱の .mcp.json が含まれています）。現在のインストール手順については、マーケットプレイス／プラグインのドキュメントを参照してください。longhand setup の手順4では上記の claude mcp add コマンドが表示されますが、自動実行はされません。

Claude Desktop： longhand mcp install を実行して、Longhand を Claude Desktop の設定に追加します（--skip-mcp を指定しない限り、longhand setup でも実行されます）。これは Claude Desktop の設定ファイルのみを書き換えます。Claude Code には影響しません。

クライアントを再起動すると、13個のツールを利用できます。 コア（検索可能なアーカイブ）：

• search — セッション、プロジェクト、ツール、ファイル、event_type のフィルターを使ったセマンティック検索（すべて組み合わせ可能）です。session_id とともに context_events を渡すと、各一致項目を前後の会話とともに取得できます。クエリテキスト自体にプロジェクト名が含まれていて、明示的な project_id／project_name／session_id が指定されていない場合、結果はそのプロジェクトに自動的に絞り込まれます（ペイロードは {auto_scoped_to, auto_scope_hint, hits} になります）。自動絞り込みを抑制するには明示的な session_id を渡すか、プロジェクトフィルターを指定して意図的に絞り込みます。現時点では、ほかに絞り込みを上書きする方法はありません（#102）
• list_sessions — プロジェクト／時間で絞り込める最近のセッションです。project_id（および任意の since／until）を渡すと、そのプロジェクトの成果情報が追加されたセッションのタイムラインを取得できます
• get_session_timeline — オフセット／末尾からのページネーションと、要約のみのスキャンモードを備えた時系列ビューです（tail: N は「最新のイベントは何か／どのように終了したか」を確認できます）
• replay_file — 指定した時点のファイル状態を再構成します
• get_file_history — すべてのセッションにわたるファイルの編集履歴を取得します
• get_stats — ストレージ統計情報です（説明には data_dir フィールドが含まれるとありますが、実際には返されません — #106）

プロアクティブメモリー：

• recall — あいまいな自然言語での検索（まずはこちらを使用してください）です。会話セグメントとセッションのタイムラインをもとに、作業に明確な証拠が残っている場合は、問題→修正のエピソードを高精度で提示するナラティブを構成します。1.2.2 以降、時間指定のないクエリで最上位の一致が30日以上前であり、かつ次点よりも30日以上古い場合、その旨を先頭に注記します（ランキングは変わりません）。この確認を省略するには、時間表現を追加してください
• recall_project_status — 「X の作業はどこまで進んだか？」に答える、コミット、イシュー、直近の成果を含む Git 対応のプロジェクト概要です
• find_episodes — 問題→修正のペアを構造化して検索します。1つのエピソードの詳細（参照イベント、差分、修正後のファイル状態）を取得するには、episode_id を渡してください
• list_projects — 推定されたプロジェクトを閲覧します。あいまいな候補とそのスコア付き理由を取得するには、match を渡してください
• list_plans — 履歴全体にわたる ~/.claude/plans/*.md へのすべての Write/Edit を取得します

Git 履歴：

• find_commits — すべてのセッションを対象に、コミットメッセージ、ハッシュのプレフィックス、またはブランチ名で検索します。または、クエリを指定せず session_id を渡すと、1つのセッションの Git 履歴を時系列順に取得できます

自己修復：

• reconcile — longhand reconcile をラップします。古さを示すバナーが表示された後、Claude がセッション内から再帰属と再取り込みを行えます。デフォルトではドライランです（適用するには fix=true を渡します — v1.0 でデフォルトが切り替わりました）

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)

出力の上限処理は一様ではなく、すべてに適用されるわけではありません。search、get_session_timeline、recall、recall_project_status、find_commits は max_chars を受け付けます（無効にするには 0 または負の値を渡しますが、通常その必要はありません）。list_sessions と list_projects は、デフォルトモードの場合のみ固定の16,000文字で切り詰められます。list_sessions(project_id=…) と list_projects(match=…) は、以下の上限なしの処理経路を通ります。get_file_history、replay_file、get_stats、find_episodes（一覧モードでは1件ではなく最大 limit 件を返します。デフォルトは20、最大は1000です。1件に絞られるのは episode_id の詳細モードのみです）、list_plans、reconcile は、クエリの結果を上限なしで返します（#103）。全容についてはトークン予算を参照してください。

インストールすると、「先週のセッションで認証ミドルウェアについて何を決めた？」 のように Claude に尋ねられ、Claude は過去の作業を実際に検索します。

自動取り込み

longhand hook install は ~/.claude/settings.json に 2 つのフックを追加します。Stop はターン間のライブ追跡用、SessionEnd はセッション終了時の完全な分析処理用です。両方がまとめてインストールされ、一方だけを追加するフラグはありません。インストーラーは longhand を絶対パスに解決し、各コマンドを Claude Code のフックスキーマでラップします。

{
  "hooks": {
    "Stop": [
      {"matcher": "", "hooks": [{"type": "command", "command": "/abs/path/to/longhand ingest-live"}]}
    ],
    "SessionEnd": [
      {"matcher": "", "hooks": [{"type": "command", "command": "/abs/path/to/longhand ingest-session"}]}
    ]
  }
}

どちらのコマンドもフックの標準入力 JSON から transcript_path を読み取るため、フックエントリ自体にフラグは不要です。

• Stop フック（ingest-live） は、アシスタントの各ターン後に実行されます。トランスクリプトファイルを追跡し、新しいイベント（ツール呼び出しのペアリングとセッション統計を含む）を段階的に保存するため、作業中のセッションでも、作業を続けながら list_sessions、タイムライン、ファイル履歴、リプレイから照会できます。埋め込みは行わないため、セマンティックな recall／search には SessionEnd の処理、または reconcile --fix の処理が引き続き必要です。ライブ追跡されたセッションには project_id が付与されず、reconcile の null_project バケットに入るため、reconcile --fix では完全な分析を伴って再取り込みされます。ここでの失敗は、ターンを妨げるリスクを決して生じさせないよう、意図的に通知されません。標準出力にも記録用の痕跡にも出ず、バックストップは SessionEnd と reconcile が担います。
• SessionEnd フック（ingest-session） は、セッション終了時に 1 回実行されます。プロジェクトの推定、結果、エピソード、セグメント、埋め込みを含む完全な分析処理を行います。ここで失敗すると、標準エラー出力に 1 行を表示し、logs/hook-errors-YYYY-MM-DD.log に記録用の痕跡を残します（doctor で確認できます）。その後、終了コード 0 で終了します。

どちらもノンブロッキングで、1～2 秒で実行されます。以後、どちらについても気にする必要はありません。

任意のバックグラウンド調整機能： longhand schedule install-reconciler は、スケジュールに従って reconcile --fix を実行する launchd plist を追加します。フックが取りこぼしたセッションも、トランスクリプトがまだディスク上にあれば検出できます。reconcile は ~/.claude/projects/ から列挙するため、Claude Code がすでにローテーションして削除したトランスクリプトは、ここにある他のツールと同様、検出できません。

Codex に対応

Codex Desktop または Codex CLI も使っていますか？Longhand はそれらのスレッドも同じアーカイブに取り込みます。そのため、Claude Code で尋ねた質問に Codex で行った作業をもとに回答でき、その逆も可能です。

pip install -U longhand
longhand codex-sync                                                  # capture Codex threads on this machine (up to 50/run)
claude mcp add --scope user longhand-shared -- longhand shared-mcp   # keyword search across both clients, from Claude
codex mcp add longhand -- longhand shared-mcp                        # the same server from Codex (Desktop: config.toml, see the docs)

以降、reconcile --fix でも新しい Codex スレッドを取り込むため、スケジュール実行される調整機能によって両方のクライアントを最新の状態に保てます。スレッドの書き込み中は、正確な記録のみが保存されます。記録はそのままの形で検索可能で、モデルは読み込まれません。スレッドが 30 分間更新されないと、完全なパイプラインが実行されるため、何も再実行しなくても recall で確認できます。ただし、スケジュールに従って何かがポーリングしていることが条件です（launchd の調整機能、codex-sync --watch ループ、または以下の codex-sync 用 launchd テンプレート）。何もポーリングしていない場合、codex-sync --semantic が完全なパイプラインを直ちに実行します。Codex が自身のために起動したスレッドはデフォルトでスキップされ、UI ミラーが二重に保存されることはありません。未知の記録形式の変化は、他の不整合と同様に doctor に表示されます。セットアップ、制限事項、macOS の launchd テンプレートについては、docs/codex.md を参照してください。

アーキテクチャ

longhand/
├── parser.py           — JSONL → typed Events (a short list of known harness-bookkeeping entry types is skipped, not stored)
├── codex.py            — Codex rollout capture + 30-minute-quiet finalizer, shared archive
├── replay.py           — deterministic file state reconstruction
├── redaction.py        — opt-in secret-shaped-string masking
├── update_check.py     — best-effort pypi.org freshness check (most commands; the hooks and the hidden `mcp-server` are excluded)
├── types.py            — Pydantic models
├── storage/
│   ├── migrations.py      — version-aware schema evolution
│   ├── sqlite_store.py    — structured data + full raw JSON preserved
│   ├── vector_store.py    — ChromaDB: events, sessions, projects, segments, episodes (5 collections)
│   └── store.py           — unified ingest pipeline
├── extractors/         — per-event (errors, file refs, topics, git ops)
├── analysis/           — per-session (project, outcomes, episodes, embeddings)
├── recall/             — per-query (time parsing, project match, narrative)
├── demo/               — sandboxed sample corpus for `longhand demo`
├── cli/                — Typer CLI with Rich output (`_commands.py`, `helpers.py`)
├── mcp_server.py       — Model Context Protocol server (13 tools)
├── lightweight_mcp.py  — `longhand-shared`: 4-tool keyword-only server, no model loaded
└── setup_commands.py   — hook install, mcp install, config, doctor

信頼できる情報源： SQLite です。各イベントの生 JSON はすべて BLOB として保持されます。ChromaDB は検索インデックスであり、セマンティック検索に必要なものだけを保持します。

分析レイヤー： クエリ時ではなく、取り込み時に実行されます。プロジェクト、セッションの結果、エピソードを事前に計算するため、recall クエリを高速に実行できます。完全に決定的で、LLM は使用しません。

Recall パイプライン： query → time parse → project match → episode search → rank → load artifacts → narrative。完全な recall 呼び出しでは、複数のベクトル検索（イベント、プロジェクト、エピソード、セグメントに加え、条件を緩和した再試行）が行われ、その後アーティファクトを読み込み、ナラティブを構成します。著者の実データを使い、プロセス内でウォーム状態にて 2026-09-27 に測定した結果（統計を参照）：ベクトル検索 1 回の中央値は約 29ms、完全な recall 呼び出しの中央値は約 128ms です。

比較

要約メモリと Longhand は、それぞれ異なる問題を解決します。要約メモリは、多くの会話をまたいで圧縮されたコンテキストを必要とする、長期的なパーソナルアシスタントに適しています。Longhand は、過去の Claude Code 作業をフォレンジックに調べる必要がある開発者に適しています。つまり、言い換えではなく、正確な差分が必要な場合のアクセスを提供します。

統計

2026-09-27 に、作者の稼働中のストアを対象に測定したコーパス（Apple M4、macOS、コードは main）：

• 792 件のセッション（うち 6 件は Codex）
• 269,067 件のイベント
• 45 件のプロジェクトを自動推定
• 1,809 件の問題→修正エピソードを抽出
• 6,632 件の会話セグメント（設計、ストーリー、デバッグ、議論、計画）
• 3,723 件の Git 操作を抽出
• ストレージ容量：SQLite が 5.9 GB、ChromaDB が 1.6 GB

同じコーパスと日付で測定したレイテンシ（ウォーム状態、プロセス内、8 件の scripts/recall_diff クエリ）：

• recall（パイプライン全体）：中央値約 128ms（16 回実行）
• ベクトル検索：中央値約 29ms（24 回実行）
• SQL タイムライン読み取り：中央値約 1.6ms（24 回実行）
• 新しいプロセスでの最初の recall 呼び出し（モデルとインデックスの読み込み、コールドスタート）：約 0.6s

トークンの上限

最もよくある質問は、「Claude が Longhand を使うと、トークンを大量に消費しますか？」です。

ほとんどの場合、いいえ。ただし、上限はすべてのツールで共通ではないため、この表をご確認ください。 13 個のツールのうち 5 個は、Claude が出力を見る前に出力を切り詰め、ページネーションのヒントを付加します。さらに 2 個は固定サイズで上限を設けていますが、デフォルトモードの場合に限られます。残る 6 個は、クエリで生成された内容を上限なしで返します（#103）。実際には、get_file_history／replay_file は自然に 1 つのファイルに対象が絞られます（ただし、編集履歴が長い場合やファイルが大きい場合は、出力も大きくなることがあります）。注意が必要なのは find_episodes です。デフォルトの list モードには自然な範囲の絞り込みがなく、完全なエピソード行を最大 limit（上限 1000）件まで上限なしで返す可能性があります。一方、episode_id を使う detail モードでは、1 つのエピソードに対象が絞られます。

重要な理由 — 比較：

• セッションの生の JSONL を直接読む場合： 1 セッションあたり 50K～200K トークン（Claude Code のセッションは通常、それぞれ 1～5MB です）。
• より大きなコンテキストウィンドウを使う方法： プロンプトごとに、毎回履歴全体のトークンを消費します。
• 要約ベースのメモリツール： クエリごとのコストは低いものの、思考ブロックはすでに破棄されています。

Longhand は一定コストです。上限はコーパス単位ではなく、呼び出し単位です。10 個のセッションから想起する場合も、1,000 個のセッションから想起する場合も、返されるトークン量は同じ範囲内に収まります。また、Longhand 自体は API を一切呼び出しません。消費されるトークンは、Claude が読み取る MCP ペイロードだけです。あなたとデータの間に LLM は介在しません。

調整方法： 上記の 5 つのツールは max_chars パラメーターを受け付けており、呼び出しごとに値を下げられます。get_session_timeline で summary_only: true を指定すると、content フィールドが除外され、ペイロードが約 10 分の 1 に縮小されます。

617 件のユニットテストに合格しており、13 個すべての MCP ツールの一覧表示とディスパッチを対象としています（list_plans のハンドラーだけは個別の呼び出しテストがありません）。完全なセキュリティ監査の結果：重大な指摘 0 件、深刻な指摘 0 件。メインのストアを開く経路では ~/.longhand/ がアクセス許可 0700 で作成されます（一部の初期書き込み経路では、まだこのモードが適用されていません — #99）。すべての SQL はパラメーター化され、すべての入力には上限が設けられています。依存関係：chromadb、posthog、typer、rich、pydantic、mcp。

作者

Nate Nelson。Idaho Falls 在住。コンピューターサイエンスの学位はありません。自分に見えるものを説明し、翻訳は任せるというやり方で、14 の業界でソフトウェアを構築してきました。

GitHub：Wynelson94

ライセンス

MIT。自由にお使いください。