Eggshell 开源本地记忆工具：用 Lean4 编写，为 AI 智能体跨会话省 token

AI 记忆。更少 token。
在独立的 AI agent 对话之间复用先前的工作，使用本地记忆，无需 LLM 调用来组织它。

获取插件 · 安装 · 亲自试试 · 观看演示 · 工作原理 · 证据 · 控制项 · 隐私

Eggshell 是帮助 AI agent 使用更少 token 的本地记忆。 它把一次对话中的工作转化为下一次对话可复用的证据：仓库 搜索、命令、文档发现和结论。把有用的工作 带入新对话，避免重复你已经做过的调查。

记忆在本地构建和组织，无需 LLM 调用，也无需为记忆管理支付额外的 token 费用。你的 agent 仍会消耗正常的任务和 交接 token。参见实测的 token 节省量及其适用范围。

为什么要用证据图？

有用的记忆需要的不仅仅是一个先前的答案。它需要支撑该答案的 观察、该答案成立的条件，以及在下一次问题不同时 找到相关部分的方法。

Eggshell 将这些连接保存在一个原始工作与证据的图中。 本地语义搜索找到相关工作；图遍历引入其 支撑性的工具结果、源位置和必要的上下文。交接 保留选定的原始段落及其关系，无需额外的 LLM 调用来总结或组织记忆。 代码、自然语言、文档和命令输出使用相同的结构。

这种组合是 Eggshell 的核心：语义检索、相互关联的 证据、不可变的历史和可复用的图计算，以 Lean 契约实现。 保存的工作保持可检查，而索引化的有界 读取让引擎无需为每次搜索重建整个记忆 即可检索上下文。工作原理解释了该设计。

同一任务。两个新对话。比较 token 使用量——30 秒。

真实的 Codex CLI、Luna xhigh、在较早版本上的独立临时对话。在这组录制的配对中， Eggshell 在第二个对话中输入 + 输出 token 减少了 81.8%；两个 答案都通过了静态源审查。仅一组配对，为清晰起见对时间进行了剪辑。 全分辨率视频和测量细节 · 在两个对话中试试。

使用已发布的 Codex 插件，或单独的、实验性的 适用于 Claude Code、Gemini CLI、Cursor 和 OpenCode 的适配器。 这些适配器使用相同的记忆引擎，并单独构建和安装。 它们有自动化的引擎集成测试；尚未针对这四个客户端 评估实时 agent 会话和 token 节省情况。

安装

对于 Claude Code、Gemini CLI、Cursor 或 OpenCode，请遵循 适配器安装指南。以下步骤安装 Codex 插件。

你需要 Apple Silicon/ARM64 或 x86-64 上的 macOS 或 Linux、Python 3，以及可作为 codex 使用的 Codex CLI。你的 Codex 客户端必须支持插件和命令 钩子。安装过程会下载 Eggshell 二进制文件和本地搜索模型。

1. 安装插件， 然后向 Codex 提问：“为此项目设置 Eggshell。” 安装过程会安装 运行时和搜索模型并准备项目，同时保留现有设置。
2. 在/hooks中启用它，然后在项目中开始一个新聊天。
3. 检查启动消息：“Eggshell session hook connected”。运行 !egg doctor 检查设置。如果消息缺失，检查/hooks。 完成双聊天示例并使用!egg graph来 确认已保存的工作能传递到后续对话。

初始设置完成后，记录和相关交接都是自动的；普通 任务无需特殊提示。一旦钩子被信任，缺少设置会产生启动通知。 此集成需要 Codex 命令钩子；普通的 ChatGPT Chat 不提供自动 Eggshell 记忆。

改为从终端安装

curl --proto '=https' --tlsv1.2 -fsSL \
  https://raw.githubusercontent.com/momonpya/eggshell/main/install.sh | sh
export PATH="${EGGSHELL_PREFIX:-$HOME/.local}/bin:$PATH"
cd your-project
egg init

安装程序会检查发布校验和，安装插件和egg 命令，并准备本地搜索。如有需要，将相同的 PATH 设置添加到你的 shell 配置中。在 Codex 中，通过/hooks查看并启用 Eggshell 的钩子，然后在项目中开始一个新聊天。

egg init创建.eggshell.toml并配置.eggs/work.egg，即项目的 本地记忆数据库。它存储为一个目录， 包含仅追加的页面文件和已提交的头部。.eggs目录被 Git 忽略。数据库在第一个回合被保存时出现。

在两个聊天中试用

使用小型公共示例获取可复制的任务提示、 基线测试，以及已保存工作和交付交接的检查点。 它不需要私有仓库。要在你自己的项目中试用 Eggshell：

1. 在已初始化项目的 Codex 聊天中，提出一个真实的调查问题， 例如“找出配置是如何加载的，并确定相关测试。”
2. 让 Eggshell 在调查进行过程中保存工具结果，并在回合停止时保存最终 答案。!egg keep可以显式刷新已完成的回合。
3. 在同一项目中打开另一个 Codex 聊天，提出相关的后续问题， 例如“如果我们添加一个新的配置选项，应该更改哪些测试？”
4. 运行!egg graph以检查实际发送给 Codex 的先前工作。

开头的!在 Codex 中运行 Eggshell 控制命令，而不进行模型回合。 在终端中，使用egg init或egg uninstall codex，不带!。

告诉我们你的首次运行情况—— 无论是成功了，还是在设置、保存或交付时停止了。一份简短报告能帮助 我们改进那些阻碍你的步骤。

Eggshell 在搜索相关工作之前会记录每个工具结果。一个独立的 写入器在回合仍在运行时将这些观察保存到.egg；最终答案在回合停止时保存。被中断的写入会保持排队并 自动重试。!egg keep可以显式保存已完成的回合；!egg drop 清除活动回合，而不删除已保存的观察或排队的提交。

关于读取多个记忆数据库、自定义安装位置和故障排除，请参阅 插件指南。

工作原理

1. 保存原始观察。钩子在回合期间记录工具结果。 一个独立的写入器将不可变的工作和结果添加到本地页面 数据库，包含分块正文、来源记录和搜索索引。
2. 搜索索引，跟随图谱。本地 MiniLM 和文本排名找到 相关工作。Eggshell 在消耗正文读取预算之前，会在其支持图谱中对原始证据进行排名。它加载选定的上下文，而不是为每个钩子重建整个已保存图谱。
3. 复用已校验的计算。 持久化的依赖涵盖命中、缺失键、范围以及原始正文引用。当这些依赖一致时，排序和图计算可以复用；新的匹配记录或源变更可能使相关缓存结果失效。
4. 提供有用的证据。 Eggshell 在有限交接范围内为当前问题选择原始段落和支撑性图上下文。它保留源位置、条件和例外及其相关解释，并避免重复发送已在可见聊天上下文中传递过的段落。

Eggshell 在复用前检查记录的本地文件依赖。已更改或删除的文件不会重写原始观察：其先前内容仍作为历史保留，确认的新内容成为单独的观察。工作区相对路径和内容指纹支持在不同检出之间迁移记忆。仅凭匹配的文件名无法认证外部或 MCP 结果。

该设计遵循三项原则：

• 保留证据。 原始观察保持不变。新内容和更正作为单独记录，带有各自的来源和条件。
• 仅复用适用的工作。 相似性找到有用的上下文；记录的依赖决定本地证据是否仍然适用。智能体使用已校验的证据，仅调查当前请求中缺失的事实。
• 让用户保持控制。 记忆保留在本地，记录可以禁用，并且可以检查确切交付的上下文及其选择。

搜索和图处理在本地运行。Eggshell 不要求 LLM 编写摘要、对记忆分类或维护图。选定的记忆和智能体后续工作仍消耗模型正常的输入和输出 token。引擎、适配器、检索选择、设置逻辑和包构建器用 Lean 编写。Python 仅限于 FastEmbed 推理和现有的 NumPy 数值内核；它不组织记忆或选择交接。 参见 已验证的契约和运行时边界。 参见 架构参考 了解匹配、图操作和 Lean 核心。

控制与检查

在相关的 Codex 聊天中运行这些：

!egg                  show active settings and staged turn
!egg keep             save the staged turn now
!egg drop             clear the active turn (saved work is retained)
!egg diff             preview what would be saved
!egg graph            show the exact handoff sent to Codex
!egg why              explain the handoff selection
!egg inspect          show resolved storage paths
!egg doctor           check setup without changing settings or memory
!egg off              disable memory and clear the active turn (saved work is retained)
!egg on               enable memory again
!egg next private     read memory without saving the next turn
!egg next off         disable memory for the next turn

配置文件指定可以读取哪些记忆数据库以及新工作保存到哪里。默认的 work 配置文件读写项目的记忆。private 为只读；它仍将相关的已保存工作发送给 Codex。off 同时禁用记录和交接。更多控制和配置。

证据

从一个新种子到三项调查，然后复用

在 2026-10-10，我们使用原生 macOS Codex CLI、GPT-6 Luna、xhigh、独立临时聊天比较了三项相关的 Clang Driver 调查：

1. 一个目标/语言边缘情况及其测试边界。
2. 公共 API、配置、下游影响以及一个最小的附加测试。
3. --target、-x 和 -fsyntax-only 通过作业构造的交互。

记忆辅助序列从空开始，记录了一个新种子调查，然后运行主题 1 → 2 → 3。每个主题的工具结果和答案在下一次聊天前被保存并索引。第二轮使用累积的记忆重复 1 → 2 → 3，并全程持续保存。新答案从未导入记忆。

每个新参考都是独立的聊天，没有 Eggshell 记忆，在同一天早些时候用相同的问题、LLVM 快照、原生 CLI、模型和推理设置记录。每个主题有一个全新参考，两个缩减列都复用它。

Token 是输入 + 输出，包括缓存输入；推理包含在输出中。每个缩减都使用对应的全新参考。所有七个新的记忆侧聊天均已完成；没有需要排除的失败尝试。新种子花费了 766,235 tokens，与后续表格分开。种子加上两次辅助轮次共消耗了 1,975,215 tokens。记忆组织本身没有使用 LLM 调用。这是一个初始序列和一个保留记忆序列，没有对模型随机性的控制；这不是通用的节省保证或统计比较。

答案审查：静态源审计发现，辅助答案解决了问题，并保留了目标、输入、阶段和作业构建边界。对提议的测试夹具和源链接的小修正与未编辑的答案一起记录在测量记录中。审查由一名审查员进行，没有盲法。该快照没有经过验证的 LLVM 构建，因此未建立运行时测试和统计质量等价性。

钩子性能：最慢的钩子在第一轮为 17.3 秒，在第二轮为 23.6 秒，在 30 秒的截止时间内。没有发生超时或不完整的初始交接。每个答案都被持久化，并在下一个主题之前完成索引，所有先前的观察都保持完整。保留记忆轮次在所有三个主题中需要零额外工具执行。未测量峰值内存。

测量记录包括确切的提示、token 计数、计时、交付的数据包、持久性检查、答案和源审查笔记。它标识了 Eggshell 提交 237058c 和 LLVM 提交 6dfe1677ab8dffbc6ec13d53a1e0215d75147689。 请参阅已验证的契约及其边界，了解 Lean 独立于这些测量所证明的内容。

隐私

Eggshell 没有托管服务、遥测或账户系统。保存的工作、嵌入和搜索处理都留在您的机器上。选定的先前工作作为模型输入传递给您的代理，并按照其模型提供商的设置和条款处理，就像聊天中的其他上下文一样。

安装会下载发布版、Python 依赖项和 MiniLM 模型。工作文件可能包含提示、源代码和工具结果；请谨慎选择项目可以读取哪些文件。只读模式会阻止保存新工作，但不会阻止将现有记忆发送给代理。

有关存储位置、网络行为和删除，请参阅 PRIVACY.md。通过 SECURITY.md 中的私有渠道报告漏洞。

开发

源代码构建使用固定在 lean-toolchain 中的工具链。

lake build eggshell eggshell_tests
EGGSHELL_DATA_ROOT="$PWD/.lake/eggshell-tests-data" \
  .lake/build/bin/eggshell_tests

要安装源代码构建：

lake build eggshell
EGGSHELL_PREFIX=/absolute/install/root \
  .lake/build/bin/eggshell install codex
export PATH="/absolute/install/root/bin:$PATH"
egg init

在更改持久图或做出性能声明之前，请参阅 CONTRIBUTING.md。品牌资产记录在 docs/brand.md 中。

Eggshell 是预发布软件。由不兼容的开发检出创建的持久化数据可能会被拒绝，而不是被静默重新解释。

许可证

根据 Apache-2.0 许可。