EachOf：30 分钟抓重点

先读每题的短回答。被继续追问，再展开原理和实现。第一轮先看 1、2、4、5、6、11、12、14、16、20。

一、先把项目讲明白

二、Embedding：最容易被继续问的原理

三、项目具体实现：讲清数据怎么走

四、工程追问与效果验证

项目依据沿用已核对的 EachOf 版本 7b1cc48；算法常识与当前项目实现已分别说明。代码入口 · 完整来源
原理参考：Sentence Transformers 模型结构 · 对比学习 · pgvector 距离与索引

AI 记忆到底是什么

先把模型当作“拿着材料回答的人”

你向模型提问时，应用会把问题、指令、相关历史等组成一份输入材料。这份材料叫上下文（Context）。模型根据这份材料和训练时学到的能力生成回答。

普通推理调用不会因为你说“我主要写 Java”，就自动把这句话永久写进模型参数。下一次调用能否知道，取决于应用有没有重新提供相关信息，以及它使用了什么记忆机制。

四个容易混淆的东西

为什么不把所有聊天都塞回去

输入长度有上限，传入更多内容通常也增加成本和处理时间。大量无关、重复、已过时的信息还会干扰回答。例如旧方案和新方案一起放进去，却没有说明哪个仍有效，模型可能选错。

所以长期记忆需要做两件事：保存有价值的信息；在当前问题下选出仍然适用的信息。

记忆的四个基本动作

1. 提取：从“聊了很多内容”中选出可能长期有用的陈述。
2. 存储：保存文字，以及属于哪个项目、来自哪里、何时有效等信息。
3. 检索：新问题来了，查找相关且允许使用的记忆。
4. 提供上下文：把选中的记忆交给 Agent 或回答流程，由其用于生成回复。

RAG、记忆、Agent 的关系

RAG 即检索增强生成：先查资料，再让模型结合资料作答。长期记忆可以采用这条读取路径，同时还需要管理信息如何写入、纠正、过时和撤销。

Agent 可以理解为围绕模型运行的一套程序：接收目标、调用工具、观察结果、继续行动。EachOf 提供可调用的上下文能力；Agent 负责何时调用，以及如何使用结果。

用一个故事贯穿全过程

下面是教学示例：你在做一个“座舱资料助手”，先决定日志保留 30 天，后来调整为 7 天。所有示例记录与数值只用于解释机制。

第一天：记下一条项目决定

你说：“这个项目的诊断日志保留 30 天，方便排查偶发问题。”

1. 把这段信息交给 EachOf，并指定“座舱资料助手”这个 Space。
2. 处理器提取候选陈述：“诊断日志保留 30 天”。
3. Core 校验候选与来源，把它写成带状态的记忆。抽取内容最初是 suggested，不能直接当作已确认事实。
4. 确认后，后续有权限的 Agent 可以查询到它。

第二天：换一个 Agent 继续

你问：“帮我设计日志自动清理方案。”新 Agent 通过接入的工具查询项目记忆，EachOf 返回“保留 30 天”及相关来源信息。Agent 再结合当前任务给出方案。

这里需要同时满足：Agent 连接到了 EachOf、有该 Space 的权限、发起了查询，并实际使用返回的上下文。仅仅安装服务，不代表所有 AI 会自动共享记忆。

第三天：决定调整为 7 天

你把记忆改成“保留 7 天”。假设系统之前根据旧记忆产生过派生结论：“30 天以前的日志可以清理”。这条结论的依据已变化，需要退出当前可用结果，等待重新计算。

同样，如果曾缓存“日志保留多久？”的答案“30 天”，也不能只看缓存还在就返回。系统需要重新检查引用的记忆和版本。

第四天：撤销一份资料的使用授权

你撤销了某个来源。系统应立即阻止后续受控检索继续使用由该来源支撑的相关内容，后续再异步做索引清理、隔离和对象清除。

用一张表记住整个故事

本章依据：docs/architecture/overview.md · core/internal/operations/commit.go · core/internal/operations/candidate_refs.go

Memory、Space、Connection

一条记忆为什么需要这么多附加信息

只有一句话，你很难知道它属于哪个项目、谁说的、是否还有效、是不是模型猜的。附加信息用来回答这些问题。

// 教学数据结构，非 EachOf 接口的精确字段定义
{
  id: "m-log-policy",
  content: "诊断日志保留 7 天",
  space: "座舱资料助手",
  source: "已确认的项目决定",
  status: "confirmed",
  validSince: "2026-09-20",
  recordedAt: "2026-09-23",
  semanticRevision: 2
}

六种对外状态

两个时间，解决两类问题

有效时间：事实在现实里何时成立。记录时间：系统何时得知或记录这件事。

例：9 月 20 日开始改成保留 7 天，但 9 月 23 日才录入。问“9 月 21 日实际是什么规则”，应看有效时间；问“9 月 21 日系统当时知道什么”，应看记录历史。迟到的信息让这两个时间有了不同意义。

本章依据：docs/product/model.md · README.md

把整体架构讲清楚

每一层具体负责什么

为什么 Go 和 Python 分开

平台层需要稳定地处理权限、状态、并发和存储；模型处理层需要接入不同算法与模型。通过有版本的协议分开，可以独立替换或重启处理器。处理器离线时，已提交记忆的读取、撤销和任务查看仍应可用。

代价也要说出来：多一个运行时，就多一份部署、接口版本和故障定位成本。分层是否值得，取决于是否需要这些隔离和扩展能力，不能只说“Go 快、Python 适合 AI”。

一个容易讲错的细节：查询向量怎么生成

写入时的向量化属于后台处理任务。读取时，用户问题需要及时转换成查询向量；真实模型场景使用独立的私有 Python 查询向量服务，通过有超时限制的同步调用完成。

这个查询服务没有数据库写权限，也不是异步任务 Worker。它失败时，语义检索通道不可用，关键词检索仍继续，并返回降级标记。

本章依据：docs/architecture/overview.md · docs/architecture/query-embedding-service.md

一条记忆如何写进去

先认清 Operation 和 Task

Operation：用户发起的一次完整操作，例如“记住这个网页”。Task：完成该操作的一项内部工作，例如抓取、抽取、向量化。

一个操作可以拆成多项有前后依赖的任务。所有任务加起来形成一张有向无环图，简称 DAG。类比 Android：提交一项完整后台工作，内部再组织若干有顺序或可并行的步骤；这里涉及跨进程与持久化，机制比进程内线程池更完整。

以记住网页为例

1. Capture：取得资料，建立原始资源与事件记录。
2. Extract：提取可长期保留的候选陈述。
3. Concept / Embed：进行概念处理和向量化，部分步骤可并行。
4. Consolidate：整合已有内容与新内容，减少重复或处理关系。
5. Generalize：从具体信息中形成更一般的候选结论。

这是架构文档中的示例任务链，不意味着每一种写入请求都必须跑完全部步骤。

候选结果为什么不能直接入库

模型可能提取错，处理器也可能存在缺陷。更严重的是，计算期间权限或来源已经变化。处理器拿到输入时可以用，不代表交结果时仍然可以用。

因此处理器不能直接连接数据库，也不能自行写成权威记忆。它只交候选结果，Core 校验协议与结构、任务身份、来源、权限和策略，并按任务类型完成幂等写入。这一步叫 Trusted Commit。

“已接收”不等于“已经记住”

请求被接受后，操作可能仍在排队或处理中。客户端需要查看操作状态，判断最终成功、失败或需要重试。后台任务的失败不会把已经接受的那个 HTTP 响应重新变成失败响应。

本章依据：docs/architecture/overview.md · core/internal/operations/commit.go

怎么找回真正相关的记忆

关键词检索：看你用了什么词

查询“pgvector 索引”时，包含这个专有名词的记忆通常很有价值。全文检索会把文本处理成适合搜索的形式，再匹配查询和评估相关性。不同语言的切词与配置会影响结果，中文不能默认与英文效果相同。

语义检索：看表达的意思是否接近

你问“以前决定把数据存在哪里”，记忆写的是“项目使用 PostgreSQL”。两句话用词不完全一样，但含义相关。Embedding 模型把文本转换成一组数字，即向量，让系统能够比较表达之间的接近程度。

混合检索怎么理解

关键词通道擅长处理明确词语；向量通道补充语义相近的候选。系统把两路结果合并、排序，再检查适用性。两路结合是可用策略，效果仍需要在实际数据上验证，不能自动推出一定比单路好。

一次读取，按这六步讲

1. 识别调用者：确定其身份与有效授权。
2. 限定范围：只允许目标 Space 中可访问的内容进入受控查询。
3. 取得候选：关键词搜索，并在语义通道可用时结合查询向量搜索。
4. 检查有效性：排除被撤销、过时、不再有有效推导依据等不适用内容。
5. 组织上下文：排序，控制条数和 token 预算，附带来源信息。
6. 交给使用者：Agent 或回答服务收到上下文，再用于当前任务。

这是便于讲解的逻辑顺序。实际代码可能在数据库查询、服务层、答案提交和缓存读取等多处重复校验，不能把安全约束只放在最后一步。

为什么要有 token 预算

Token 是模型处理文本的计量单位，与汉字或单词没有固定一一对应关系。找回 100 条记忆，并不代表都应塞进输入；上下文需要留给问题、指令和回答。预算限制让返回内容有明确上限。

Recall 和 Ask 有什么不同

Recall：找回相关记忆。Ask：结合可用记忆形成答案，需要处理引用、答案提交和可能的缓存。找回一条正确资料，并不等于最终答案一定正确。

本章依据：docs/architecture/overview.md · docs/architecture/query-embedding-service.md · docs/benchmarks/recall-precision-investigation.md

基础延伸：PostgreSQL 全文检索

纠正、撤销与旧答案失效

先分清三种关系

纠正：旧依据与新依据不是同一个版本

原记忆内容发生语义变化时，需要能区分修改前后。派生结果提交时携带它所依据的来源快照，Core 检查其中的版本等信息是否仍与当前来源匹配。

例：处理器拿到版本 1（30 天），运算期间用户改为版本 2（7 天）。处理器晚交的旧结论不能直接写成当前有效结论，需要按新投影重新处理。这就是防止“过时计算把旧事实写回来”。

读取现有派生内容和答案时也要检查依赖是否仍当前有效。仅在生成时校验一次，挡不住生成之后的变化。

撤销：先阻止使用，再处理清理

架构中的来源撤销使用短事务，把撤销标记（tombstone）、访问日志和 outbox 事件一起写下。受控召回立即排除被撤销来源影响的内容；隔离、重建索引与物理清理放到后台。

Outbox 可以理解为“和业务变更一起保存的待处理通知”。如果只改状态、再临时发一条通知，程序在中间崩溃，后续工作可能丢失；把通知也写进同一事务，后台就能继续读取并处理。

纠正、撤销、删除的区别

缓存也必须检查依据

“命中缓存”只说明以前算过。返回前还需要确认支持它的记忆没有被撤销、替换或变得不再有效。依据不可用时，应停止返回旧答案；需要时用当前上下文重新生成。

一致性的边界

立即：安全撤销后的后续受控读取不能继续使用该来源。最终完成：语义重新处理和后台清理可以稍后完成。系统有时暂时缺少新的派生结果，也应避免返回已经无效的旧结果。

另外，无法保证外部 Agent 已取得的文字被自动抹去；跨系统撤回需要接收方配合。

本章依据：docs/architecture/overview.md · core/internal/operations/candidate_refs.go · core/internal/ask/current_state.go · core/internal/operations/commit.go

后台任务为什么能恢复

用“领任务”理解租约

一个 Worker 从 Core 领取 Task，同时取得有期限的执行资格，叫 Lease（租约）。处理期间发送 Heartbeat（心跳） 告诉 Core 自己仍在工作。进程崩溃或失联后，租约到期，任务可以重新安排。

这比“在内存里标记正在执行”更可靠，因为处理器或主机重启后，任务状态仍保存在外部。

为什么重复执行不可避免

Worker 做完了，提交请求的回复却在网络中丢失。Worker 无法判断服务端有没有成功，只能查询或重试。租约过期后，新旧 Worker 也可能短时间都以为自己在做同一项任务。

EachOf 的架构约束是任务至少一次执行（at-least-once），提交路径具备幂等性（idempotency）。它不等于任务永远只运行一次，而是重复交同一结果不会重复制造本应只有一份的权威数据。

幂等不只是加一个请求 ID

外部操作根据范围、类型、调用者、输入、有效策略等形成语义约束。同一个幂等键对应同一请求，返回原操作；同一个键被拿来提交不同请求，应报冲突。

在已查看的抽取提交实现中，陈述与事件采用确定性标识和已存在检查等方式处理重复写入。不同任务的幂等细节要按各自提交路径检查。

故障场景怎么解释

与你熟悉的 Android 怎么联系

可以把 Processor 类比为后台工作执行者，把 Core 调度器类比为管理任务生命周期的服务。但线程池只管理当前进程中的线程，不能直接提供跨机器租约、持久化任务和提交一致性。

本章依据：docs/architecture/overview.md · core/internal/operations/commit.go

Agent 怎样真正用上记忆

API、SDK、MCP 各是什么

MCP 是接口协议。它不负责自动挑出高质量记忆，也不保证宿主一定调用某个工具。真正何时查、查什么、怎么用，仍由宿主和 Agent 工作流决定。

一次实际接入需要哪些步骤

1. 运行服务并完成身份配置。
2. 建立或选择 Space，明确允许访问的内容。
3. 为 Agent 配置受限凭证和连接入口。
4. 把记忆查询能力接入宿主，设定调用方式或显式触发。
5. 确认结果真的进入模型上下文；更进一步检查回答是否正确使用。
6. 验证撤销权限后，后续调用无法继续访问。

这是接入检查路径，不是可直接执行的完整部署命令；具体配置要遵循当前仓库与宿主版本。

Space updates、Pinned context、按需查有什么区别

Continue 不是任务执行断点。第一次查看建立比较边界；后续增量为空，不代表 Space 没有记忆。Standing 也不是每次请求都会自动附加。

什么是 Context Receipt

可以理解为一次上下文交付的回执，记录向 Agent 提供了哪些内容，便于追溯。已返回内容不能直接证明模型实际使用了它，更不能直接证明任务因此完成得更好。

本章依据：docs/product/continuity.md · docs/architecture/overview.md

协议延伸：MCP 服务端能力概览

怎样证明项目有效

四层验证

先理解三个指标

Precision@K：前 K 个结果里，相关结果占多少。示例：返回前 5 条，其中 4 条相关，Precision@5 = 4/5 = 80%。

Recall@K：全部应找回的相关资料中，前 K 条找回多少。示例：共 10 条相关资料，前 5 个结果覆盖 4 条，Recall@5 = 4/10 = 40%。某些问答评测用“有没有命中一个正确支持项”作为 recall@K 的查询级定义，必须读具体评测口径。

MRR：看第一条相关结果排第几。排第 1 得 1，排第 2 得 1/2，排第 5 得 1/5，再对查询求平均。它关心用户多快遇到第一条相关结果。

为什么指标会“看着进步，实际不可比”

换了数据集、模型、噪声量、K 值或“相关”的判定方式，数字就可能不能直接比较。例如按字符串出现判断相关，会把偶然命中当成功；按完整词覆盖判断，又可能漏掉同义表达。

所以讲任何提升，都要补充：相对哪个基线、在什么样本上、用什么模型、按什么规则、重复了几次。

当前资料怎么讲才准确

过往讨论中的“Precision@5 提升 3.75 个百分点”属于特定受控小样本、相对无衰减基线的结果，不能直接当作当前整体性能结论。本 Wiki 不把它放进默认项目讲述稿。

这次读取的仓库检索调查记录了 LoCoMo 场景下的排序不足，以及相关性判定规则与数据适配带来的评价限制；旧版 precision 与新版 recall 不能放在同一比较中。

一个可执行的演示验证清单

1. 在 Space A 写入并确认一条规则，记录来源。
2. 授权的 Agent 在新会话查询，检查是否返回该规则及依据。
3. 把 30 天改为 7 天，再查询原问题，检查旧答案是否被阻止或替换。
4. 撤销来源，再从召回和答案路径检查。
5. 用仅能访问 Space B 的身份查询，检查是否隔离。
6. 在测试环境重试同一操作，检查没有重复权威记录。

这是建议的验证脚本思路，本次没有执行。报告时附上环境、版本、输入、输出与测试结果，才能称为当次验证证据。

本章依据：docs/benchmarks/recall-precision-investigation.md · docs/architecture/overview.md

把项目讲成自己的话

先理解，再复述。下面讲述只覆盖当前读取到的架构与机制，不包含未经核实的个人贡献、企业生产规模或性能领先结论。

30 秒版：让不懂 AI 的人听明白

EachOf 是我做的 AI 长期记忆项目。使用 AI 做一个长期项目时，换了会话或工具，经常要重新解释背景。EachOf 把项目偏好、决定和依据保存起来，让有权限的 Agent 按需找回。用户也能查看、纠正和撤销这些记忆；来源变了以后，系统会检查旧结论和答案是否还能继续使用。

90 秒版：说明核心流程

EachOf 解决的是跨会话、跨 Agent 的项目上下文延续问题。它把长期信息组织成 Memory，放在有权限边界的 Space 中，通过 Connection 接入外部应用或 Agent。

写入时，Python 处理器提取候选记忆，Go Core 负责校验来源、权限和数据约束，再正式写入。读取时，结合关键词与向量检索，找出相关且仍有效的记忆，在预算内交给 Agent。

我关注的一个重点是记忆变化后的影响。比如日志保留规则从 30 天改成 7 天，不能只改原记录，还要检查基于旧版本产生的结论和缓存答案。架构上通过来源、推导依赖和版本校验处理这些问题；异步任务则用租约、重试与幂等提交提高可靠性。效果需要分别验证检索质量和实际使用收益。

3 分钟版：按照这五段展开

卡壳时，回到这六个动词

记住 · 校验 · 找回 · 使用 · 纠正 · 撤销

每个动词解释一句，串起来就是完整项目。名词是为解释动作服务的。

技术选择怎么讲得有说服力

使用“需求 → 选择 → 获得什么 → 付出什么 → 怎么验证”这个顺序。例如：“需要计算与权威写入隔离，所以把 Python 处理器放在进程外，通过协议交结果；这样可替换和重试，但增加部署与协议维护成本；需要通过故障测试验证恢复行为。”

暂时不要这样表述

常见追问与直接回答

先口头回答，再展开。每道题的第一段直接回答问题，后面补充原因或例子。

从概念走到仓库

不要从所有目录一起读起

写入路径：先读这几个位置

DefaultCommitter.Commit 先验证候选 JSON，再根据任务种类分发；commitExtract 把抽取出来的陈述置为 suggested，并采用确定性标识处理重复写入。

继续看 answerSupportingClaims：它在答案提交时检查引用的来源与记忆，过滤不可用依据，并调用 IsClaimInferenceCurrent 检查推导是否仍然当前有效。

语义版本：重点看什么

candidate_refs.go 中存在对来源快照 SemanticRevision 与当前记忆版本的比较。找出错误 ErrInferenceNeedsReprojection 的返回条件，再追调用者怎样重投影或重试。

不要只找到一个函数名就认定所有路径都安全。一次完整代码走查应把 HTTP、MCP、缓存、导出等实际相关读取路径分别列出来，查看它们是否复用或补足必要校验。

读不懂 Go 时，先找“边界”

1. 输入：谁调用？参数来自用户、任务，还是处理器？
2. 状态：读了哪些当前记录？是否可能并发变化？
3. 校验：什么条件返回错误、跳过或重试？
4. 写入：哪些字段被修改？重复执行会怎样？
5. 输出：返回事实、候选、状态，还是上下文投影？

本章依据：core/internal/operations/commit.go · core/internal/operations/candidate_refs.go · core/internal/ask/current_state.go

术语速查与阅读来源

遇到生词时查这一页。先记住它在流程中做什么，再记住英文。

项目来源

本 Wiki 以 shane654/eachof 的固定版本 7b1cc48e7d340bde18903cd025093847909d168a 为主要参考。链接指向当时读取的版本，后续仓库变化不自动更新本页。

• README.md
• docs/product/model.md
• docs/architecture/overview.md
• docs/architecture/query-embedding-service.md
• docs/product/continuity.md
• core/internal/operations/commit.go
• core/internal/operations/candidate_refs.go
• core/internal/ask/current_state.go
• docs/benchmarks/recall-precision-investigation.md

基础阅读

• PostgreSQL：全文检索入门
• MCP：服务端工具与资源概览

项目源码链接可能需要你自己的仓库访问权限。

最后一次闭卷检查

现在合上页面，回答：“记忆从哪里来、由谁校验、怎么找回、变了怎么办、失败怎么办、如何证明有用？”这六个问题能连贯回答，你就已经能讲清项目主线。