lethe

LETHE

Live Ephemeral Token & History Engine — LETHE は大きなツール出力を LLM エージェントのコンテキスト外に退避し、必要に応じて呼び戻します。長時間のタスクにかかるトークンを削減できます。

🌍 この README は英語とスペイン語の二言語対応です。English · Español

---

🔌 Claude Code または Codex で使う（今すぐトークンを節約）

LETHE は MCP サーバー として提供されます。2 行設定するだけで、エージェントは大きな出力をコンテキスト外に移し、必要に応じて呼び戻せるようになります。長時間のタスクで使うトークンを削減できます。／LETHE は servidor MCP として提供されます。2 行設定するだけで、エージェントは大きな出力をコンテキスト外に移し、必要に応じて呼び戻せるようになります。長時間のタスクで使うトークンを削減できます。

Claude Code:

pip install "lethe-llm-context[mcp]"
claude mcp add lethe -- lethe-mcp

Codex: ~/.codex/config.toml に MCP ブロックを追加します。詳しくは integrations/codex/mcp-config.md をご覧ください。

次に、エージェントが自分でアーカイブするよう、ガイド用スキルを追加します。 integrations/claude-code/SKILL.md。

公開されるツール：lethe_archive · lethe_recall · lethe_status。 詳しいガイド：integrations/claude-code/mcp-config.md。

---

▶️ 動作を見る（API キー不要）／Míralo funcionar (sin API key)

python -m lethe.examples.mcp_demo

  LETHE — offload big tool outputs, recall on demand, save tokens

The agent runs 4 commands. Each returns a wall of text:

  → build.log               857 tok in context  —archive→  stub '[paged: build.log | handle=6d48a1c2]'
  → pytest.txt              479 tok in context  —archive→  stub '[paged: pytest.txt | handle=1e56b0f4]'
  → db_dump.json            829 tok in context  —archive→  stub '[paged: db_dump.json | handle=ec02...]'
  → trace.txt               414 tok in context  —archive→  stub '[paged: trace.txt | handle=d888...]'

lethe_status:  4 blocks archived, 2579 tokens moved out of context

30 steps later the agent needs a buried fact. It recalls by keyword:

  lethe_recall("launch_code")  →  found launch_code = 4242 (rehydrated losslessly from the archive)

  Context window cost
    without LETHE :  2579 tok  (everything stays resident)
    with LETHE    :    38 tok  (only tiny stubs remain)
    saved         :  2541 tok  (-99%)

これは、MCP ツールで使われるものと同じロジックを実行します — lethe_archive / lethe_recall / lethe_status。

---

English

LETHE とは（現時点での正直な説明）

LLM エージェントが長時間のタスク（数十から数百のステップ）を実行すると、以前は役立っていたものの、もう必要のない情報でコンテキストウィンドウが埋まっていきます。古くなったツール出力、30 ステップ前に読み込んだファイル、大きな JSON ダンプなどです。その結果、各ターンで使うトークンが増え、コストが上がり、最終的にはコンテキストの上限に達します。

LETHE は、エージェントに外部のロスレスなスクラッチストアを提供します。大きなコンテンツはコンテキストウィンドウの外側に置かれ、内部には短い参照ハンドルだけが残ります。使い方は 2 通りです。

1. MCP サーバーとして使う（上記のインストール方法）。 エージェントは大きな出力に対して lethe_archive(content) を呼び出し、返された 4～8 文字のハンドルだけを保持します。後で lethe_recall(handle) または lethe_recall("keywords") を呼び出すと、全文を取り戻せます。削除されるものは一切なく、呼び戻しはロスレスです。ガイド用スキルがエージェントにこれを実行するタイミングを伝えるため、ほぼ自動的に行われます。これはプロバイダーに依存せず、どの MCP ホスト（Claude Code、Codex）でも動作します。

2. Python ライブラリとして使う（ループ内のコンテキスト GC）。 ContextManager はエージェントのループ内で自動処理を実行します。ヒューリスティックな Curator が各ブロックをスコアリングします（新しさ、後続のブロックから参照されているか、ブロックの種類、および任意で安価なモデルに関連性を問い合わせる処理）。そして Archivist が最も使われていないブロックをストアに退避します。ロスレスでスタブを残しながら、作業セットがトークン予算内に収まるようにします。参照されたハンドルは、必要に応じて再び読み込まれます。

仕組みを明確にしておきましょう。 MCP サーバーがホストのコンテキストウィンドウを書き換えることはできません。LETHE は、エージェントに明示的な退避／呼び戻しツールと、それらの利用をほぼ自動化するスキルを提供して動作します — 魔法で実現しているわけではありません。大切なのは、その点を正直に伝えることです。

✅ 現在使える機能と 🗺️ 今後のロードマップ

以下に示すマルチプロバイダー、アンサンブル、セマンティック検索の設計は、長期的なビジョンであり、 実装済みの機能ではありません。現在の状況を正確にお伝えします。

機能	状況
MCP サーバー：archive / recall / status、ロスレス	✅ 動作し、リリース済み
ほぼ自動でオフロードするためのガイドスキル	✅ 動作し、リリース済み
Python ライブラリ：ヒューリスティックな Curator ＋予算に応じた追い出し＋ロスレスページング	✅ 動作し、テスト済み
Needle-in-a-haystack の実証（作業セットを予算内に保持し、事実を復元）	✅ 1721→199 tok、約88%削減
Curator での低コストモデルによる関連性スコアリング（任意）	✅ 動作（Claude／任意のアダプター）
想起検索	🟡 語句／キーワード検索（SQLite FTS5）。セマンティック検索は未対応
Compactor（古い実行履歴を要約して、密度の高いメモに変換）	🟡 コードベースにはありますが、自動ループにはまだ組み込まれていません
プロバイダー	🟡 現在は Claude とテスト用アダプターに対応。GPT／Gemini／Llama は設計済みですが、未実装です
アンサンブルキュレーション（複数モデルによる投票）	🗺️ ビジョンの段階で、着手していません
埋め込み／セマンティック検索	🗺️ ビジョンの段階で、着手していません
1 行の wrap() によるドロップイン	🗺️ ビジョンの段階で、着手していません
完全な評価ハーネス（LoCoMo、アブレーション、レイテンシ）	🗺️ needle 評価のみ実施済み

各マイルストーンはタグ付きリリースとして公開されます。詳細は CHANGELOG.md をご覧ください。

メンタルモデル（OS との類推）

LETHE は、仮想メモリを管理するオペレーティングシステムのように設計されています。この類推がアーキテクチャの指針です。上記の ✅／🟡 は、そのうちどこまでが現在自動で動作するかを示しています。

オペレーティングシステム	LETHE
物理 RAM	コンテキストウィンドウ（作業セット）
ディスク	外部ストア（SQLite／メモリ内）
ページテーブルエントリー	コンテキストに残されるスタブ／ハンドル
ページフォルト時のページイン	追い出されたブロックの再読み込み
追い出しポリシー	Curator（関連性スコアリング）— 現在は ✅ ヒューリスティック方式
コールドページの圧縮	Compactor（統合ノート）— 🟡 まだ組み込まれていません
固定／スワップ不可メモリ	ピン留めされたブロック

LETHE とエージェントメモリライブラリの違い

Mem0、Zep、Letta などは、セッションをまたいで事実を保持します。LETHE が対象とするのはその反対で、 実行中のループにおけるセッション内のライブな作業コンテキストを管理し、今この時点でウィンドウに何を残すかを決めます。長期記憶製品を補完するものであり、競合製品ではありません。 この違いが決定的かどうかは、今後のロードマップで実証していく必要があります。

クイックスタート（API キー不要）

python -m pytest -q                  # run the full test suite, including the needle test
python -m lethe.examples.fake_loop   # WATCH it work: live view, blocks paging out, budget held

実際の Claude デモ

$env:ANTHROPIC_API_KEY="sk-..."   # PowerShell
python -m lethe.examples.claude_loop

設計ドキュメント

• docs/specs/2026-06-12-lethe-vertical-slice-design.md — 実装済みスライスの承認済み設計
• docs/LETHE_engineering_design.md — 長期的なエンジニアリングビジョンの全容（マルチプロバイダー、 アンサンブル、埋め込み）。現在の状況ではなく、ロードマップとしてお読みください。

ライセンス

Unlicense に基づき、パブリックドメインとして公開されています。誰でも、どこでも、自由に利用できます。

---

スペイン語

LETHE とは（現時点での正直な説明）

LLM エージェントが長いタスク（数十から数百のステップ）を実行すると、コンテキストウィンドウは、かつては役立っていたものの、もう役立たない情報でいっぱいになります。古くなったツールの結果、30ステップ前に読み込んだファイル、巨大な JSON ダンプなどです。その結果、ターンごとのトークン数が増え、コストが増加し、最終的にはコンテキスト上限に達します。

LETHE は、重いコンテンツをコンテキストウィンドウの外に置き、ウィンドウ内にはごく小さなハンドルだけを残せるよう、エージェントにロスレスな外部ストアを提供します。使い方は 2 通りです。

1. MCP サーバーとして使う（上記のインストール方法）。 エージェントは大きな出力に対して lethe_archive(content) を呼び出し、4〜8 文字のハンドルだけを保持します。その後、lethe_recall(handle) または lethe_recall("palabras") を呼び出して、テキスト全体を取り戻します。データは決して削除されず、リコールはロスレスです。ガイドスキルがエージェントにいつ実行するかを指示するため、ほぼ自動的に行われます。プロバイダーに依存せず、どの MCP ホスト（Claude Code、Codex）でも動作します。

2. Python ライブラリとして使う（ループ内でコンテキスト GC）。 ContextManager はループ内で自動パスを実行します。ヒューリスティックなCuratorが各ブロックをスコアリングし（新しさ、後続のブロックから引用されているか、ブロックの種類、さらに任意で安価なモデルの呼び出しも加味）、Archivistがより古いブロックをストアにページアウトします。ロスレスでスタブを残しながら、トークン予算内にワーキングセットを維持します。参照されたハンドルは、必要に応じてページインされます。

仕組みについて率直に説明します。 MCP サーバーは、ホストのコンテキストウィンドウをひそかに書き換えることはできません。LETHE は、エージェントに明示的なオフロード／リコール用ツールと、それらをほぼ自動的に使わせるスキルを提供することで動作します。魔法ではありません。この誠実さが大切です。

✅ 今日動作する機能と 🗺️ ロードマップ上の機能

以下に示すマルチプロバイダー設計、アンサンブル、セマンティック検索は、長期的なビジョンであり、実装済みの機能ではありません。現状を正直に分けると、次のとおりです。

機能	状態
MCP サーバー：ロスレスな archive / recall / status	✅ 動作、公開済み
ほぼ自動でオフロードするためのガイドスキル	✅ 動作、公開済み
ライブラリ：ヒューリスティックな Curator ＋ 予算に基づく追い出し ＋ ロスレスなページング	✅ 動作、テスト済み
針を干し草の山から探すテスト（予算内のワーキングセット、データの復元）	✅ 1721→199 tok、約 88% ↓
Curator での任意の安価なモデルによるスコアリング	✅ 動作（Claude／任意のアダプター）
リコール検索	🟡 語彙／キーワード検索（SQLite FTS5）、セマンティック検索は未対応
Compactor（古い実行を密度の高いノートに要約）	🟡 コードにはあるものの、ループには未接続
プロバイダー	🟡 現時点ではClaudeとテスト用アダプター 1 つ。GPT／Gemini／Llama は設計済み、未構築
アンサンブルによるキュレーション（複数モデルの投票）	🗺️ ビジョン、未着手
埋め込み／セマンティック検索によるリトリーバル	🗺️ ビジョン、未着手
1 行のドロップイン wrap()	🗺️ ビジョン、未着手
完全な評価ハーネス（LoCoMo、アブレーション、レイテンシ）	🗺️ 現時点では needle eval のみ

各マイルストーンはタグ付きリリースとして公開されます。詳細は CHANGELOG.md をご覧ください。

メンタルモデル（OS にたとえると）

LETHE は仮想メモリを管理するオペレーティングシステムとして設計されています。このたとえはアーキテクチャの指針であり、上記の ✅／🟡 は、そのうちどこまでが現時点で自動的に動作するかを示しています。

オペレーティングシステム	LETHE
RAM	コンテキストウィンドウ（ワーキングセット）
ディスク	外部ストア（SQLite／メモリ内）
ページテーブルエントリー	コンテキストに残るスタブ／ハンドル
ページフォールト時のページ取得	追い出されたブロックの再水和
追い出しポリシー	Curator（関連性をスコアリング）— 現時点では ✅ ヒューリスティック
古いページの圧縮	Compactor（統合ノート）— 🟡 まだ未接続
固定／スワップ不可のメモリ	固定（pinned）ブロック

エージェントのメモリライブラリとの違い

Mem0、Zep、Letta などは、セッション間で事実を保持します。LETHE が目指すのはその逆です。 実行中のループのセッションのライブコンテキストを管理し、今この瞬間にウィンドウ内に何を残すかを決定します。長期記憶製品と競合するのではなく、補完するものです。 この違いが決定的かどうかは、上記のロードマップで今後実証する必要があります。

クイックスタート（API キー不要）

python -m pytest -q                  # corre toda la suite, incluida la prueba de la aguja
python -m lethe.examples.fake_loop   # VELO funcionar: vista en vivo, bloques paginándose, presupuesto sostenido

実際の Claude を使ったデモ

$env:ANTHROPIC_API_KEY="sk-..."   # PowerShell
python -m lethe.examples.claude_loop

設計ドキュメント

• docs/specs/2026-06-12-lethe-vertical-slice-design.md — 実装したスライスの承認済み設計
• docs/LETHE_engineering_design.md — 長期的なエンジニアリング構想の全体像 （マルチプロバイダー、アセンブリ、埋め込み）。ロードマップとして読み、現状を示すものではありません。

ライセンス

Unlicense のもとでパブリックドメインとして公開されています。誰でも、どこでも自由に利用できます。