Echo Memory

Echo Memory

为 AI Agent 提供共享记忆，以图的形式存储在你自己的数据库中。 Claude Code 学到的内容， Cursor 和 Codex 也能回忆起来。每条事实都会记录是谁、何时写入的，服务端绝不会调用模型来存储事实。

_{上方的每一行都是实际输出，来自针对临时数据库执行这些命令的结果。完整记录见 .github/branding/demo-transcript.txt。}

你的 Agent 每次会话开始时都一无所知。通常的解决办法是把笔记文件粘贴到上下文中， 但文件会不断变长，里面大多内容都与你当前的问题无关。Echo Memory 采用另一种方式：将事实相互关联，并通过查询返回少数相关事实。在作者自己的 325 条事实存储中，对于同一个答案，上下文量减少了 96.7%，而在基于作者答案生成的 1,190 次查询中，仍有 87.2% 的情况下能找到该答案。

write_episode                          query_memory
  billing ──uses──▸ Razorpay             "how do we take payments"
    │ written by claude-code               ▸ billing uses Razorpay, not Stripe
    │ supersedes ──▸ Stripe                  written by claude-code, 3 days ago
    └ no model invoked                     ▸ 1,372 tokens, not 41,838

安装

要求： Python 3.11+ 和 Docker（用于数据库）。

pipx install echo-mem
echo-memory quickstart

quickstart 会启动数据库、应用架构，并输出用于注册服务的 claude mcp add 命令，其中会填入实际使用的端口。Postgres 镜像已发布，因此无需编译。

也可以使用托管服务，无需运行数据库：

pipx install echo-mem
echo-memory connect <key>          # a key from https://app.echo-mem.com

然后，在每台机器上执行一次，让 Agent 知道何时记录和回忆，而不只是知道这些工具的存在：

echo-memory install --global

之后请重启客户端。 MCP 服务是一个长期运行的进程，会持有启动时加载的代码和配置； 可编辑安装不会改变这些内容。

PyPI 上的名称是 echo-mem，而不是 echo-memory。 后者属于一个无关的托管产品。 导入包和 CLI 的名称分别是 echo_memory / echo-memory； 只有发行包名称不同。

升级

pipx upgrade echo-mem
echo-memory init-db                # apply any new migrations
echo-memory reindex                # rebuild what the new code derives

必须按顺序执行这两个步骤；对于版本早于你刚安装版本的存储库，两者都不可省略。

跳过 init-db 会明显报错。 如果代码读取旧于当前代码的架构，会引发未定义列错误——这还算好的情况：它会停止，而不是基于自己只理解了一部分的数据作答。

跳过 reindex 则会静默失败，后果更糟。 新代码以不同方式读取的派生数据仍是旧数据，而且不会报错。具体来说，升级到 0.5.3 后，词法语料统计会被视为过期，直到重新构建；因此 BM25 会保持关闭，查询仍按 ts_rank 排序，而设置却显示为开启。reindex 会同时重建嵌入和这些统计数据。之后可以运行 echo-memory health 查看状态。

用法

echo-memory status                 # what each scope holds, and which agents have written
echo-memory health                 # a score, what is weak, and what to do about it
echo-memory dashboard --serve      # the graph, in a browser, localhost only

echo-memory why <fact_id>          # the full audit trail for one fact
echo-memory recall "<question>"    # query the store from a terminal
echo-memory export                 # everything, as JSON

echo-memory install --for cursor   # wire one client, project scoped
echo-memory adopt                  # wire every MCP client on the machine, each with its own id

echo-memory infer-causal-hints     # type the facts whose own sentence states a cause (dry run)

echo-memory eval                   # retrieval quality against your own store
echo-memory eval --context         # what a recall costs against injecting everything
echo-memory eval --context --sweep # the same, as a curve across corpus size
echo-memory eval-external locomo <path>       # LoCoMo, the corpus the published figures use
echo-memory eval-external longmemeval <path>  # LongMemEval, the same
echo-memory calibrate              # is entity resolution trustworthy on your data
echo-memory benchmark              # write, query and digest latency

七个 MCP 工具

工具	功能
write_episode	存储实体以及连接它们的事实。不调用模型。
query_memory	混合向量和全文检索，并通过倒数排名融合结果。全文检索使用 BM25 排名。接受 as_of，以读取存储在某个时刻的状态；也接受 about，以返回针对一个或两个指定实体记录的事实。
trace_cause	沿着与主题匹配的实体追踪因果链，而不是返回排序列表。
record_recall_save	标记回忆出的事实有助于解释某件事。若事实未被任何读取操作返回，则拒绝记录。
get_audit_log	记录对记忆的每一次更改，并附上通俗易懂的原因。
pending_documents	本项目写入、但图谱尚未收录的记忆文件。
mark_ingested	将其中一项标记为已处理。

你将获得什么

图，而不是列表。 实体是节点，事实则是连接两个节点的边。 两个彼此毫不知情的会话会根据名称映射到同一个实体，因此第二个会话能继承第一个会话学到的内容。

为有界检索做好了设计，但尚未实现。 计划是，随着时间推移，旧的、很少读取的记忆会降级为更高层级的摘要，不会丢弃任何内容，并且每条摘要仍会通过边关联回其来源事实。目前这些功能都不存在：没有分层，没有摘要，而当前的检索会遍历作用域内的所有有效事实。相关内容记载在 docs/designs/ 中，并在下文列为 v1c；本段以前曾用现在时声称这些功能已经实现。

返回排序后的答案，并说明每条事实为何入选。 每条返回的事实都带有 score（与查询的余弦相似度）、rank（位置）和 matched（找到该事实的检索通道）。score 刻意不使用融合分数：倒数排名值是 1/(k+rank) 的总和，在不同查询之间没有可比性；而相似度始终代表同一含义，这正是调用方据此设定阈值时所需要的。每条返回的事实都会计算 score，包括仅由全文检索找到的事实，因为通过哪个通道检索到事实属于实现细节，不应影响调用方用来判断相关性的字段。

全文检索通道按 BM25 排序。 Postgres 的 ts_rank 只计算词项出现次数，不考虑其他因素：没有逆文档频率，因此某个作用域中每条事实都包含的词，其权重与只在三条事实中出现的词一样；没有饱和机制，因此重复次数会线性增加得分；没有长度归一化，因此长事实会因篇幅较长而受罚。在 324 条真实提示词上，第 3 名和第 4 名的得分有 59% 完全相同；而倒数排名融合只读取排名位置，从不读取其背后的分数，因此按扫描顺序排列的通道会让融合结果变成掷硬币般的随机选择。

BM25 通过 SQL 计算，而非安装扩展，因此不会向你的数据库添加任何扩展。语料统计信息会在写入时，于已持有作用域锁的事务中分摊重建，也会通过 echo-memory reindex 重建；没有统计信息的作用域会回退到 ts_rank，而不会基于缺失的统计信息排序。ECHO_MEMORY_LEXICAL_BM25=0 会让所有地方恢复使用 ts_rank。

关于某个实体的事实，是相似度无法表达的。 query_memory 接受 about 参数，其中包含一个或两个实体名称，并且只返回针对这些实体记录的事实。提供一个名称时，返回与该节点相连的边；提供两个名称时，返回它们之间任一方向的边。这就能实现“两个名称出现在同一条事实中”的检索，而且无需检查事实文本。

这不是排序方面的改进，也不能替代排序改进。查询某个团队时，可能会返回一条语义上相近、但谈论另一个团队的事实，因为这条错误的事实确实与问题相似；无论如何改进排序，都无法将其排除。实体同一性不等于相似性，而事实是连接两个节点的边，因此询问一条事实涉及哪个实体，是结构性且精确的查询。

名称匹配是精确且不区分大小写的，绝不进行子串匹配，因为短名称可能是更长且无关词语的子串。如果某个名称没有任何记录，检索会返回空结果，而不是返回最接近的内容；如果一对名称之间没有相连的事实，也会返回空结果：这表示确实不存在相关记录，也就是没有人记录这件事，而不是返回某些相邻内容。超过两个名称时会拒绝查询，而不是返回空结果，因为一条边只有两个端点；涉及三个实体的事实不是这个模型能够表达的查询。

存储库始终保留的历史记录如今可以读取。 从首次迁移开始，每条事实就一直带有 t_valid 和 t_invalid，但读取路径过去只会询问事实当前是否有效。因此，存储库付出了保留作用域全部信念记录的代价，却无法回答事后分析时最先提出的问题。query_memory 接受以 Unix 秒为单位的 as_of，所有通道都会遵循该参数：向量、全文、图遍历和摘要。 正是事实取代机制，让这不只是件新奇事。再次写入相同的来源、目标和关系，但更改了主张，并不会编辑旧事实，而是结束它：旧边会获得 t_invalid，并且仍可查询。任何内容都不会被重写，因此历史是真实存在的，而不是事后重建的。这正是记忆再巩固文献所放弃的属性，也是本项目拒绝采用这一理念的原因。

重述一个未改变的主张不算改变，现在也不会再被视为改变。如果事实文本、置信度和因果提示都与现有边完全一致，就会跳过写入，并在 restated 下报告。过去，这会创建第二条边、结束第一条边，并发出一个 before_fact 与 after_fact 相等的取代记录。这就是一条客户边携带同一句话的 47 个版本，以及 543 次写入只产生 112 个事实、却每次都收费的原因。这也让重试变得安全：在没有幂等键的情况下，调用方重试一条实际上已成功的写入，过去会为它额外消耗一个版本。

每次写入都会说明是否存储了内容。 write_episode 可能通过四种不同方式以空的 edges_created 结束，而从调用方的角度看，过去无法区分这些情况，除非知道该检查哪个其他键。现在每种情况都会报告 stored: false，并在 not_stored 中标明自身：refused（验证拒绝了写入）、deferred（某个实体提及与现有节点足够接近，值得进一步询问，但又不够接近而无法合并）、unchanged（所有事实都已逐字存在）和 no_facts（该事件没有陈述任何事实）。拒绝响应携带与成功响应相同的键，因此每种路径都能使用同一项检查；retryable 则会区分值得重试的数据库短暂故障与永远无法通过的验证错误。如果一次写入存储了部分事实，并暂存了其余事实，就会报告 partial。

暂存造成了实际数据损失，因为它看起来最像成功：响应格式正确、没有错误、isError 为 false，而且没有写入任何内容。一位客户加载了 26,633 条事实，却把它理解为 26,633 次成功，实际只存储了 1,650 条。

每条事实都有来源信息。 谁写入的、使用了哪个工具、属于哪个项目、何时写入，以及哪些读取操作返回过它。被取代的事实永远不会删除。它不再显示，但仍可通过历史记录访问。

因果类型，以及对因果关系的遍历。 一条事实可以携带 causal_hint：caused_by、led_to、enabled_by、blocked_by 或 contradicts 之一。这由 Agent 根据对会话内容的理解自行设置，绝不通过统计推断。trace_cause 会遍历这些链接并返回因果链，而不是排序列表，因为“这件事为什么会发生”的答案是一条有序链，相似性无法生成这样的链。“A led_to B”和“B caused_by A”是从相反方向表述的同一主张，两者都会组合成同一条链。

没有提示的事实是关联性的，这是默认情况，而且通常是正确的。trace_cause 返回空答案时会说明空结果的类型：没有人在此记录原因，和不存在任何因果链，是关于存储内容的两种不同事实。

为早于此功能的存储补充信息。 在 0.5.0 之前写入的事实没有提示，因此对现有存储运行 trace_cause 时没有可遍历的内容。 echo-memory infer-causal-hints 会使用你自己的模型（ECHO_MEMORY_LLM_API_KEY、ECHO_MEMORY_LLM_MODEL）重新读取已存储的事实文本，并为句子本身陈述了关系的边添加类型。默认进行试运行；--write 会应用打印出的更改，而 --clear --write 会将其撤销。 这是后期提取，而非因果发现；这一差异是通过机制保证的，而非仅作承诺。没有因果连接词的句子绝不会发送给模型，因此共现关系在产生任何成本之前就会被拒绝。每条候选关系都必须引用表明该关系的原文，而不在事实中逐字出现的引文会被丢弃，因此，基于常识推理而非阅读句子的模型不会留下任何存储内容。每条写入的提示都会经过审计并标记为后期提取，这样 --clear 才能准确删除这些内容，而绝不会删掉你在写入时写入的内容。

写入路径上不进行推理。 提取发生在调用方的 Agent 中，因此存储记忆不会在服务端调用模型。引擎中有三个命令会调用模型提供方，这三个都值得点名，而非一笔带过：上文提到的 infer-causal-hints、distil，以及用于评估已完成基准测试运行的 judge-external。它们都不构成例外。每个命令都是用户针对已存储事实手动输入的命令，不会作为写入、迁移或钩子的一部分运行；而 src/echo_memory/cli/llm.py 包含引擎中唯一一个对外请求，因此，不运行这些命令的存储操作绝不会触发模型调用。成本只是转移了，并未消失：Agent 必须在调用前准备好已提取的实体和事实，这正是工具契约所阐述的内容。这一点之所以重要，是因为 Zep/Graphiti 是最接近的架构参照，其自身对摄取过程的描述是“每个事件都会触发多次 LLM 调用”，并且“写入成本随数据量增长”。

显而易见的回应是，写入成本低，是因为做的事情更少；在机制层面，这个回应是正确的。docs/WRITE-COST.md 对此作了充分说明，其中包括这一选择的两项实测成本：Stop gate 触发了 7 次，却只产出 1 条事实；而涉及歧义实体的写入会被延后，而非存储。延后本身仍是代价；改变之处在于，现在调用会明确说明这一点，而不是返回成功的假象。

任何 MCP 客户端。 编码助手、聊天机器人、运维 Agent，或内部构建的工具。编码 Agent 是验证这一点的场景，而非适用范围的限制。

数字及其测量方式

每个数字都来自此仓库或在线存储库，并附有可在你本地复现的命令，以及测量所用存储库的规模。语料库规模较小，且已说明噪声下限，因为未经量化的差异算不上结果。

其中两个数字描述的是存储库，而非产品。eval --context 和 eval --ablate 会根据正在评分的事实构建查询，因此标签是免费的，绝对值仅适用于此存储库；它们如实反映不同配置之间的差异，但不能说明 echo-mem 在其他人的数据上会有何表现。两个外部数据集的结果才适合与其他结果进行比较。

指标	数值	复现命令
每次召回的上下文量与注入全部内容相比	在包含 325 条事实的存储库上，减少 96.7%；基于答案本身生成的 1,190 个查询，hit@10 为 0.872。因此，应将其理解为附带下限的令牌比例，而非准确率	echo-memory eval --context
语料库规模增长 8 倍时的同等节省	32 条事实时为 75.5%，增至 261 条时为 96.4%；hit@10 从 0.900 升至 0.946	echo-memory eval --context --sweep
LoCoMo 检索，1,982 个问题，5,882 轮对话	recall@10 0.601，hit@10 0.658，MRR 0.460，session@10 0.850	echo-memory eval-external locomo
LongMemEval 检索，90 个问题，每种类型 15 个	session@10 0.937，recall@10 0.727，MRR 0.428	echo-memory eval-external longmemeval --per-type 15
词法 BM25 与 ts_rank 对比	entity_pair 上的 MRR 为 +0.0271 [+0.0083，+0.0481]，multihop 上为 +0.0166 [+0.0166，+0.0381]；另外两种形态的差异处于噪声范围内，且没有任何一种表现更差	echo-memory eval --ablate，取符号反转后的 without BM25 行
服务端每次写入的模型调用次数	0	echo-memory benchmark
写入、查询、摘要延迟（中位数）	24ms、17ms、4ms；测量范围为 250 条事实	echo-memory benchmark
实体解析 AUC	0.666，95% CI [0.421，0.881]	echo-memory calibrate

最后一项结果不理想，因此特意列在这里。置信区间包含随机水平，所以已关闭无人值守合并：在自动合并阈值下，经审核的两对数据中精确率为 50%，审计日志也显示，这条路径在整个系统历史中仅触发过一次。现在，系统会将近似匹配结果交由用户确认。

LoCoMo 一项衡量的是检索，而非 QA 准确率。已发表的 LoCoMo 结果由一个模型生成答案，再由第二个模型进行评判；这里仅检查包含答案的对话轮次是否被检索出来。这只是 QA 准确率的上限，并不能替代 QA 准确率，也无法与任何已发表的 QA 数字直接比较。此外，该测试使用原始对话轮次作为输入，跳过了本设计交由调用 Agent 执行的提取步骤，因此它既是下限，也是上限。表现最差的一项是 multi hop，recall@1 为 0.099；其余结果见 docs/BENCHMARKS.md。

上下文节省量是相对于一个特定基准测得的，特意说明这一点，以免产生过度解读。这并非与“完全没有记忆”相比，后者取决于人花多少时间重新解释，无法测量。它与人们通常采用的做法相比：将项目笔记放在一个文件中，再粘贴整个文件。在该存储库中，文件包含 325 条事实，约 41,838 个令牌；平均每次召回返回 1,372 个令牌。还应同时看命中率，因为如果召回什么也没返回，得分会是 100%。

图谱

记忆是一个图谱，而不是笔记列表。实体是节点；事实是两个节点之间的一条边。这就是完整的数据模型，其他一切都由此而来。

这里有三个项目。checkout-api、mobile-app 和 data-pipeline 是在不同会话中记录的，彼此从未被告知对方的存在，但图中已经将它们区分开来，因为这种区分是边的属性，而不是任何人贴上的标签。

簇由结构决定。 通过沿边进行标签传播，将连接密集的事实分组；每个簇都以其中连接最紧密的节点命名。这就是 data-pipeline 独立成簇的原因：它所知的一切都与支付无关。这也是 checkout-api 和 mobile-app 尽管属于不同代码库，却共享一个簇的原因。它们确实共享一个概念，而这是图谱自行发现的，不是被告知的。

连通分量代表更强的断言。 不同连通分量中的两个节点之间完全不存在路径，这是此图谱所能做出的最强断言，表明两条记忆互不相关。

点击一个节点：查看它参与的所有内容

idempotency keys 是这里最大的节点，但没人刻意让它变大：来自多个服务的十七条事实按名称解析到同一个实体。面板会列出每一条事实，以及写入它的 Agent 和写入时间。

点击一条边：查看记忆为何相信它

这不是工具提示。你可以看到谁写入了这条事实、它属于哪个项目、写入时间，以及其中每个实体是如何解析的。在终端中运行 echo-memory why <fact_id> 会打印相同的追溯信息。

查看你自己的图谱

echo-memory dashboard --serve --open

上面的图片来自一个合成数据集（scripts/demo-seed.py），而不是真实存储，原因显而易见：真实的记忆图谱中充满了主机名、账号和客户端名称。

接入多个工具

为每个客户端设置各自的 ECHO_MEMORY_AGENT_ID。 Cursor 应使用 cursor，Claude Desktop 应使用 claude-desktop。无论如何，记忆都是共享的，但每条事实都会记录是哪个工具学到的；如果两个工具声称使用同一个 ID，之后就无法看出跨工具的记忆调用情况。

echo-memory adopt                  # every MCP client on the machine, each with its own id
echo-memory install [path]         # one project: MCP config plus a skill, committed with the code

adopt 会先显示差异，再写入任何内容。对于不支持 MCP 的 Agent，请参阅 docs/INTEGRATIONS.md。

图谱状态良好吗？

echo-memory health

提供评分、优势、需要关注的方面，以及相应的处理建议，其中也包括记忆调用的成本：记忆被读取的频率、读取返回了内容的频率、大致注入了多少令牌，以及这些读取带来了多少次保存。从一开始就统计了写入次数，但完全没有统计读取次数，因此无法判断记忆调用是否物有所值。即使你没有任何问题，也可以运行它，因为某个存储可能在其他各项指标上看起来都很健康，但大部分事实都来自批量导入，上一次真正的写入已是一周前，而且接入的多个 Agent 中只有一个曾写入过内容。使用 --json 可输出机器可读的结果。

其中没有任何功能设限。付费计划出售的是托管服务；对于属于用户自己的数据，不应向数据所有者隐藏诊断信息。

架构

存储 使用 PostgreSQL、pgvector 和 Apache AGE，可从单一本地 Agent 扩展到组织范围内共享的图谱，无需之后强制迁移。新颖之处在于其记忆结构和构建于其上的读写算法，而不是新的数据库引擎。

检索 v1a 使用向量与全文混合搜索，并通过倒数排名融合；全文检索部分根据每个作用域的语料统计信息，在 SQL 中计算 BM25 排名。v1b 将引入基于 networkx 的个性化 PageRank，用于多跳关联检索。

接口 使用 Model Context Protocol，让任何兼容的 Agent 都能读写同一个图谱。

状态

目前处于早期阶段，并按计划分阶段推进。架构和 v1a 到 v1b 的计划请参见 docs/designs/。

v1a，已完成	基础回忆能力。提供七个 MCP 工具、36 个 CLI 命令，已发布到 PyPI 和 MCP 注册表。
v1b，部分完成	因果类型和 trace_cause 已在 0.5.0 中发布。多跳关联检索尚未实现：对于 187 个没有单一事实能回答的问题，目前的 MRR 得分为 0.212；v1b 其余部分都必须超越这个数字。
v1c，已设计	整合：分为热数据、已整合数据和归档数据层，使检索成本不再随写入事实总量增长。目前尚未实现。
v1.1，已规划	面向整个组织的多租户：图谱可按 Agent、团队或整个组织划分。

推动 v1a 的已验证切入点是跨编码 Agent 共享记忆。这是作者日常遇到的实际痛点，也是证据最充分的应用场景。其他所有目标都是本架构旨在实现的方向。

托管服务

app.echo-mem.com 为你运行数据库：每月 $149，包含 1,500,000 个单位；一个单位指写入的一条事实或返回的一条事实。使用第一个密钥起即开始收费，因为它收费的正是托管服务；并且运行的是与你自行安装的相同的已发布软件包。

你可以免费自行运行，用于任意规模的开发、测试和评估；对于 50 人以下且营收低于 $5M 的组织，生产环境中也可免费使用，无需账户，且没有任何功能限制。超过任一门槛后，生产环境使用需签订协议：联系我们。

参与贡献

请参见 CONTRIBUTING.md。欢迎提交问题和拉取请求；请先阅读设计文档，确保提案符合分阶段构建计划。提交必须附带签署行，使用 git commit -s，即遵循开发者原创证书（DCO）。无需阅读任何贡献者协议。

最有价值的贡献，是提供与上述某个数字不符的测量结果。请在你自己的存储上运行 echo-memory eval、calibrate 或 benchmark，并附上输出结果提交问题。

许可证

Apache 2.0。 请参见 LICENSE。你可以运行、分叉、基于它构建，也可以将其集成到自己的产品中；无论规模大小，均无需签订协议，也无需征求任何人的许可。

大约有一个月的时间，情况并非如此。0.5.0 到 0.5.5 版本采用了 Business Source License，该许可证仅允许 50 人以下且营收低于 $5M 的组织免费用于生产环境。现已撤销该限制。Ateleir Tech 持有整个作品的版权，并重新许可全部内容，包括这些版本，因此授权范围只会更广，任何人都不会失去已有权利。

项目两次更改许可证，因此有必要说明缘由：这项限制保护错了对象。运行这项服务的难点不在源代码，而在于需要有人运维、备份和升级的 Postgres，以及 Apache AGE 和 pgvector。托管方案恰好销售的就是这些服务，而且不受许可证影响。与此同时，这项限制损害了项目最需要的东西：让人们无需先阅读授权条款，就能使用它。

不属于 Apache 2.0 许可范围的是托管服务本身：计量、计费和多租户功能；这些功能仅因有人需要开具账单而存在。它们都不在读写路径中。

mcp-name: com.echo-mem/echo-mem