lethe

LETHE

实时临时令牌与历史引擎 — 将大型工具输出移出 LLM Agent 的上下文，并按需取回，让长任务消耗更少令牌。

🌍 此 README 为双语版本。English · Español

---

🔌 在 Claude Code 或 Codex 中使用（立即节省令牌）

LETHE 以 MCP 服务 的形式提供。只需两行配置，Agent 就能将大型输出移出上下文，并按需取回 — 每个长任务都能减少令牌消耗。/ LETHE viene como servidor MCP. Dos líneas y tu agente saca outputs grandes del contexto y los recupera cuando los necesita — menos tokens en cada tarea larga.

Claude Code：

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

Codex： 在 ~/.codex/config.toml 中添加 MCP 配置块 — 请参阅 integrations/codex/mcp-config.md。

然后添加引导技能，让 Agent 自行归档： 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 是什么（如实介绍当前功能）

当大模型 Agent 执行长任务（数十到数百个步骤）时，上下文窗口会被曾经有用、如今已不再需要的内容填满：过时的工具输出、30 步之前读取的文件、大型 JSON 转储。这意味着每轮消耗更多令牌、成本更高，最终还会触及上下文上限。

LETHE 为 Agent 提供一个外部、无损的临时存储区，让繁重内容留在上下文窗口之外，窗口内只保留一个很短的引用句柄。使用方式有两种：

1. 作为 MCP 服务使用（上述安装方式）。 Agent 对大型输出调用 lethe_archive(content)，只保留返回的 4–8 字符句柄；之后调用 lethe_recall(handle) 或 lethe_recall("keywords")，取回完整文本。任何内容都不会被删除 — 取回过程无损。引导技能会告诉 Agent 何时执行这些操作，因此几乎可以自动完成。此方式不依赖特定提供商：可用于任何 MCP 宿主（Claude Code、Codex）。

2. 作为 Python 库使用（循环内上下文 GC）。 ContextManager 会在你的 Agent 循环中运行自动处理：启发式的 Curator 会为每个内容块评分（依据新近程度、后续内容是否引用该块、内容块类型，以及可选的廉价模型相关性调用）；Archivist 则会将最冷门的内容块分页移至存储区 — 无损保留原内容并留下存根 — 以便将工作集控制在令牌预算之内。被引用的句柄会按需分页载回。

请明确其工作机制。 MCP 服务不能悄悄改写宿主的上下文窗口。LETHE 通过为 Agent 提供明确的移出／取回工具以及让这些操作几乎自动完成的技能来工作 — 并非依靠魔法。坦诚说明这一点正是本项目的初衷。

✅ 目前可用的功能与 🗺️ 路线图规划

下方的多提供商、集成和语义检索设计是长期愿景， 而非当前已实现的内容。以下是实际情况：

功能	状态
MCP 服务：archive / recall / status，无损	✅ 可用，已发布
用于近乎自动卸载的引导技能	✅ 可用，已发布
Python 库：启发式 Curator + 预算驱逐 + 无损分页	✅ 可用，已测试
大海捞针验证（工作集控制在预算内，并成功找回事实）	✅ 1721→199 tok，约减少 88%
Curator 中可选的轻量模型相关性评分	✅ 可用（Claude / 任意适配器）
召回搜索	🟡 词法/关键词（SQLite FTS5），尚非语义搜索
Compactor（将冷运行总结为精简笔记）	🟡 已在代码库中，尚未接入自动循环
提供商	🟡 目前支持 Claude + 一个测试适配器；GPT/Gemini/Llama 已设计，尚未构建
集成整理（多模型投票）	🗺️ 愿景，尚未启动
嵌入 / 语义检索	🗺️ 愿景，尚未启动
一行式 wrap() 即插即用	🗺️ 愿景，尚未启动
完整评测工具集（LoCoMo、消融实验、延迟）	🗺️ 目前仅有大海捞针评测

每个里程碑都会以带标签的版本发布——完整说明见 CHANGELOG.md。

思维模型（操作系统类比）

LETHE 的设计类似于管理虚拟内存的操作系统。这个类比指导着架构；上方的 ✅/🟡 标明了目前有多少功能可自动运行。

操作系统	LETHE
物理 RAM	上下文窗口（工作集）
磁盘	外部存储（SQLite / 内存）
页表项	留在上下文中的存根 / 句柄
缺页时调入	重新加载已驱逐的区块
驱逐策略	Curator（相关性评分）——目前为 ✅ 启发式
冷页压缩	Compactor（整合笔记）——🟡 尚未接入
锁定 / 不可换出的内存	固定区块

LETHE 与 Agent 记忆库的区别

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 Agent 执行一项耗时较长的任务（几十步或数百步）时，它的上下文窗口会被一些曾经有用、如今却不再有用的内容填满：过时的工具结果、30 步前读取的文件、庞大的 JSON 转储。这意味着每轮需要更多 token、更高成本，最终还会遇到上下文上限。

LETHE 为 Agent 提供了一个外部、无损存储库，让大量内容存放在上下文窗口之外，而窗口内只保留一个很短的句柄。两种使用方式：

1. 作为 MCP 服务（上方的安装方式）。 Agent 对大量输出调用 lethe_archive(content)，只保留 4–8 个字符的句柄；之后调用 lethe_recall(handle) 或 lethe_recall("palabras")，取回完整文本。任何内容都不会被删除——召回是无损的。引导技能会告诉 Agent 何时这样做，因此几乎可以自动完成。这种方式不依赖特定供应商：适用于任何 MCP 主机（Claude Code、Codex）。

2. 作为 Python 库（在循环内进行上下文垃圾回收）。 ContextManager 会在你的循环中自动运行一轮处理：启发式 Curator 为每个块评分（考虑新近程度、后续块是否引用了它、块类型，以及可选的廉价模型调用），Archivist 则将较冷的块分页到存储库中——无损保留并留下存根——以便将工作集控制在 token 预算以内。被引用的句柄会按需重新分页到内存中。

我们坦诚说明其机制。 MCP 服务无法悄无声息地重写主机的上下文窗口。LETHE 通过向 Agent 提供明确的卸载／召回工具，并配合一项让工具使用几乎自动化的技能来发挥作用——并非靠魔法。这份坦诚正是重点。

✅ 现已可用 vs. 🗺️ 路线图规划

下方的多供应商设计、集成和语义检索是长期愿景，并非已实现的功能。坦诚地说：

能力	状态
MCP 服务：无损的 archive / recall / status	✅ 可用，已发布
用于近乎自动卸载的引导技能	✅ 可用，已发布
库：启发式 Curator + 按预算驱逐 + 无损分页	✅ 可用，已通过测试
大海捞针测试（工作集低于预算，数据可恢复）	✅ 1721→199 tok，减少约 88%
Curator 中可选的廉价模型评分	✅ 可用（Claude / 任意 adapter）
召回搜索	🟡 词法／关键词搜索（SQLite FTS5），尚无语义搜索
Compactor（将较冷的运行记录总结为精简笔记）	🟡 已写入代码，尚未接入循环
供应商	🟡 目前支持 Claude + 一个测试 adapter；GPT/Gemini/Llama 已设计，尚未构建
集成式整理（多模型投票）	🗺️ 愿景，尚未开始
基于嵌入的检索／语义检索	🗺️ 愿景，尚未开始
一行式即插即用 wrap()	🗺️ 愿景，尚未开始
完整评测框架（LoCoMo、消融实验、延迟）	🗺️ 目前仅有 needle 评测

每个里程碑都会作为带标签的版本发布——完整说明见 CHANGELOG.md。

心智模型（类比操作系统）

LETHE 的设计理念类似于管理虚拟内存的操作系统。这个类比为架构提供指导；上方的 ✅／🟡 表示目前已有多少功能可以自动运行。

操作系统	LETHE
RAM	上下文窗口（工作集）
磁盘	外部存储库（SQLite / 内存）
页表项	保留在上下文中的存根／句柄
缺页时调入页面	重新载入被驱逐的块
驱逐策略	Curator（评估相关性）——如今已实现启发式评分 ✅
冷页面压缩	Compactor（整合笔记）——🟡 尚未接入
固定／不可交换内存	固定块（pinned）

与 Agent 记忆库有何不同

Mem0、Zep、Letta 等会在不同会话之间持久化事实。LETHE 的目标恰恰相反： 管理运行中循环的会话实时上下文——决定此刻在窗口中保留什么。这与长期记忆产品互为补充，而非竞争关系。 这一差异是否至关重要，仍有待上文的路线图证明。

快速开始（无需 API key）

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 许可证发布到公有领域。人人皆可自由使用，随处皆然。