tigerless-labs/agent-memory

Long-term memory runtime for AI agents — plain Markdown as the source of truth, local ranked retrieval, and an independent sleep-time Manage layer. Claude Code and Codex share one store. No API key.

agent-memory 为 AI 代理提供持久记忆，使其能够跨会话保留信息。当会话结束时，代理不会忘记所学内容，该系统将记忆存储为纯 Markdown 文件，建立索引以便快速搜索，并让代理以适当的详细程度检索所需内容。

核心思想

大多数 AI 助手（如 Claude Code、Codex 或 Muse）在会话关闭时会忘记所有内容。Agent-memory 通过在磁盘上维护记忆存储来解决这个问题。Markdown 文件是唯一的事实来源——代理可以直接使用 ls 和 grep 等工具读取它们。索引（SQLite）仅作为缓存位于这些文件旁边，因此您可以删除索引并重建它，而不会丢失任何实际记忆。

检索工作原理

agent-memory 不会将大段文本粘贴到代理的上下文中，而是返回相关 Markdown 文件的路径列表。每个命中项包含一行摘要和分数。然后，代理按所需深度打开文件：仅摘要、仅标题、完整正文，甚至导致该记忆的原始源消息。这样，代理只需为其实际需要的内容付费。

主要功能

三种查找记忆的方式 – 会话开始时注入的确定性 MEMORY.md、排名 BM25 搜索（可选向量搜索）以及普通文件系统。如果一种方法遗漏，另一种方法会捕获。
写入覆盖是自动的 – 系统在自然边界（如会话结束时）自动保存记忆，因此代理无需记住执行此操作。会话的完整副本会先归档，即使蒸馏器遗漏某些内容，也不会丢失任何信息。
文件是事实，索引只是缓存 – 您可以清除 .index/ 并重建它（mem rebuild），而不会丢失任何知识。这由测试强制执行，而不仅仅是承诺。
独立的“管理”层 – 在空闲时间（如夜间），系统会整合、更新并提出删除建议，但删除仅在您确认后才会发生。它还支持时间旅行回忆（截至上周二我知道什么？）。
库内无 API 密钥，无 LLM 调用 – 判断来自宿主代理自身的 CLI，因此每次写入在转录中可见，且没有计费表面。

存储布局

所有内容都位于一个目录中（默认 ~/agent-memory-store）。它包含：

MEMORY.md – 根索引，每个记忆一行
config.toml – 所有可调参数
decision/ – 实际记忆文件，每个记忆一个，按类型和组组织
archive/ – 原始会话和来源证据的追加式副本
.index/ – 可重建的搜索索引和访问日志
.state/ – 运行时簿记（如写锁和蒸馏水印）

开始使用

需要 Python 3.12+ 和 uv。从检出安装：

git clone https://github.com/tigerless-labs/agent-memory.git
cd agent-memory
uv sync --all-packages

然后初始化存储并写入第一条记忆：

mem init
mem record --type decision --field project=agent-memory \
  --abstract "Markdown files are the single source of truth" \
  --body "Indexes are rebuildable caches."
mem recall "source of truth"

您还可以通过一行命令将其连接到 Claude Code、Codex 或 Muse：

mem setup --host claude-code

它有效吗？

README 包含 LongMemEval‑S（标准记忆评估）上的基准测试。在有界干草堆中，agent-memory 的汇总准确率为 52.9%，而 MemCore 为 35.8%，无记忆时为 5.8%。它还通过了跨主机测试：一个主机（如 Claude Code）写入的记忆可以被另一个主机（如 Codex）找到，且具体细节完整。

关于诚实性的说明

基准测试数字与已发表的 LongMemEval 分数不可直接比较，因为测试设置使用较小的干草堆——这是一项写入策略研究，而非规模研究。该项目还在仓库中提供了完整的实验协议和原始数据，因此您可以自行检查结果。

简而言之：agent-memory 让 AI 代理跨会话记住事情，使用您拥有的普通文件，无需云服务或 API 密钥。