al-buddy-memory

al-buddy-memory

Al Buddy——这里的 Al 是一个名字，读起来像「pal」，不是 A.I.。

属于你自己的记忆。

适用于 AI Agent 的便携、受治理、与模型无关的记忆。

事实会失效，绝不会被覆盖；对于受治理的句柄，擦除会遵循策略并接受审计。原始文本是事实来源，无法编辑。嵌入是可丢弃的、带模型标签的缓存。每条事实和每条链接都会导出为一种有文档说明的格式。无论产生它的是哪种模型、运行时或公司，这份记忆都能长久留存。

---

为什么要做这个项目

市面上每种 Agent 记忆产品都能很好地回答一个问题：Agent 会回忆什么？ 但没有一种能回答决定你是否能够信任并保留这份记忆的四个问题：

问题	本库	Letta	Mem0	Zep
这条事实从何而来？由谁断言？	每个节点和边都记录来源（UserInput / AIInferred / GuardianAdded / SystemGenerated）	记忆文件的 git 历史	元数据字段	图谱事件
这条事实在何时成立？又被什么取代？	两个可查询的维度：validAt 用于回答 Y 时成立的事实；getNodeAsOf / snapshotAsOf 用于根据完整的变更前后版本回答 X 时存储中的认知。两者可在一次调用中结合（snapshotAsOf(X, { validAt: Y })），无法通过历史记录佐证的读取会被标记，擦除也会删除历史记录	文件的 git 历史，而非事实模型	每条记忆的变更历史（history()：旧值、新值、事件、时间戳）——这是事务历史，而非有效时间	时态图谱（其真正优势）：Graphiti 边会同时记录 valid_at / invalid_at 和 created_at / expired_at
我能否无损地将它带到另一个运行时？	一种带版本号的 JSON 导出格式，拥有已发布的架构和一致性测试	.af（Agent 状态，受框架约束；尚未纳入归档记忆）	云端导出	自 2025 年起仅支持云端
它能否在没有供应商、密钥或服务的情况下运行？	磁盘上的 SQLite，设备端嵌入	可自托管；云端才是其产品	可自托管（Apache-2.0，使用本地向量存储）；提取信息需要大模型；云端才是其产品	Zep 是云服务；Graphiti 可自托管（需要图数据库和大模型密钥）

以上表格各单元格的依据，均于 2026-09-18 对照项目自身代码或公告核查：Mem0 的每条记忆历史存储在 SQLite 表中，包含 old_memory、new_memory、event、created_at、updated_at (mem0/memory/storage.py)；Mem0 采用 Apache-2.0 许可，可搭配包括 Qdrant、Chroma、pgvector 和 FAISS 在内的本地向量存储运行 (向量存储文档)，默认的 add() 路径会调用大模型来提取事实。Zep 于 2025-04-02 停止维护 Community Edition，用自己的话来说：“我们决定停止维护和发布 Zep Community Edition。” Zep 底层的引擎 Graphiti 采用 Apache-2.0 许可，可自托管；其声明的要求是图数据库（Neo4j、FalkorDB、Amazon Neptune 或已弃用的 Kuzu）以及大模型密钥——它“默认使用 OpenAI 进行大模型推理和嵌入”。

人们会提到的三个本地免密钥产品，依据其自身代码于 2026-09-21 核查。它们和本库一样回答第四个问题——你的机器、你的文件、无需账户——因此才是诚实的对比对象，而不是云端产品。

• basic-memory（AGPL-3.0；磁盘上的 Markdown 笔记才是真相，SQLite 是可重建的索引）。**它支持有效时间，这一点值得明说：**一条观察可以在笔记本身携带 @effective[2026-06-10,2026-07-27)，并被解析到时间索引中（models/knowledge.py），也可以从文件重建，因此文件始终是事实来源。但在本地安装中，它不记录是谁断言了某项事实：created_by / last_updated_by 字段确实存在，但保存的是云端用户 ID；在本地和 CLI 使用时则为 null。其可移植性达到最强程度，但相关规范最少：笔记本身就是格式，因此没有任何内容被锁定，也没有版本化架构可供将笔记导入其他系统。捕获和全文搜索无需密钥；语义搜索则是可选功能，且需要密钥。
• The MCP memory server（大多数 Agent 最先接触到的参考实现；使用一个 JSONL 文件）。只有实体、关系和观察，仅此而已：没有字段记录是谁说的，也完全没有时间戳；deleteObservations 会从数组中过滤掉旧值，因此过去曾为真的内容会彻底消失，而不是被标记为结束。该文件本身就是导出内容。它不会调用模型，也不会有任何数据离开设备。
• Memori（Apache-2.0；使用你自己的 SQL 数据库——SQLite、Postgres、MySQL、Oracle）。memori_entity_fact 中的一条事实包含内容、嵌入向量、计数和最后出现日期；只能通过沿外键追溯到对话消息，才能找到是谁断言了这项事实，而这并非事实本身的属性；它也不支持有效时间——date_updated 取而代之。“你的数据保存在自己的数据库中”就是它对可移植性的说明，但没有公布交换格式。就数据而言，它是本地的；但捕获并非无需密钥：提取和嵌入会调用 LLM，默认 SDK 路径也需要 Memori 账户。

另一个值得一提的是：OpenMemory MCP（Mem0 于 2025 年 5 月推出）采用了相同的分发理念——在 MCP 客户端之间共享一个本地记忆存储——但 Mem0 已将其归档；其 README 现在开篇就写道：“This project has been archived.” 它的架构正好体现了本表所讨论的差异：models.py 为记忆提供了 content、created_at、updated_at、archived_at、deleted_at 和状态字段，却没有记录是谁断言了这项事实，也没有有效时间；更新时，content 会被原地改写。它确实会保留状态转换历史和访问日志，也支持 ZIP 导出——因此，两者的区别不在于是否可移植，而在于来源记录、有效时间和不可变的原始数据。

Recall 基准测试（LOCOMO、LongMemEval、DMR）衡量 Agent 记住了什么。**这些基准都不会从来源记录、失效处理或可移植性的角度为记忆系统打分。**这个库正是为这一维度打造的，下面的符合性评分器则是衡量它的一种尝试。上面的表格是我们根据各项目自身代码和公开文档所做的整理，日期见上文；如果某个单元格有误，提交一个附带链接的 PR 即可修正。

我们仍会运行 LongMemEval，让大家熟悉的召回率数字与符合性得分并列呈现，而不是取代它；此外，我们还会运行一个自有的小型基准测试，考察召回基准所忽略的部分：当一项事实发生变化时，召回结果是否会返回当前为真的值？参见基准测试。

从这里开始

空白记忆无法为助手提供任何立足点。docs/STARTER.md 可在 10 分钟内为你打好基础：确定用户身份以及他们希望受到怎样的对待（包括“绝不做应声虫”），选择存储库要强制执行的规则，然后让它每晚推导其余内容。

从早期版本升级：CHANGELOG.md 标出了所有会改变现有调用方返回结果的变更。0.4.0 包含破坏性变更（内容不可变、受管控的擦除、存储库接口新增 listNodes，MCP 导出移至 al-buddy-memory/mcp），因此升级前请先阅读该条目。

包含内容

• MemoryStore：与存储后端无关的接口；内置 SqliteMemoryStore 和 InMemoryStore，并提供一套一致性测试套件，供任何后端运行测试。
• ProjectMemory：按项目或个人划分的独立记忆中枢，每个中枢都存放在自己的 SQLite 文件中。
• HybridRetriever：结合词法和语义检索，并采用考虑衰减的置信度；通过 transformers.js 在设备本地生成嵌入（无需 API 密钥）。检索范围可按记忆类型、标签、最低置信度、隐私和保留等级限定，且范围对关键词和向量检索同样生效。还提供两项可选辅助功能，用于回答答案散布在多次对话中的问题；两者都在读取时计算，绝不存储：reranker（本地交叉编码器 LocalReranker）会将问题与每个候选内容重新比对并重新排序；expand 会读取问题中的时间和计数线索（analyzeQuery：“in April”“the past two weeks”“how many”“A and B”）并逐项检索。
• exportPortable / importPortable：无损互换格式，带版本控制，并提供 JSON Schema。
• PinnedBlocks：大小受限的一层事实，适合放入每个提示词中；编码 Agent 可自行编辑，并构建在受治理的存储之上。
• consolidate：在空闲时运行的处理流程，读取近期原始记忆，并写入带有指向来源的溯源边的新派生事实；原始内容绝不改写，也不会被摘要取代。
• verifyDerived：每条结论都会存储其依据的确切原文（evidence），并在写入时进行核验；此功能可随时重新核验，并撤回证据不再成立的结论，但绝不删除。
• 心智模型：持续维护答案的常设问题，在后台保持更新，因此读取时无需调用模型（defineMentalModel、refreshMentalModels、getMentalModel）。每个答案都会引用其依据的事实，保留历史（“我们 6 月时是怎么想的”）；一旦其中某项事实不再成立或被删除，答案便会立即显示为过时。
• 当前状态：以每个主题一条有效记忆的形式记录“X 目前处于什么状态？”（recordState、currentStates、statesMentionedIn）。新状态会关闭它所取代的状态，并将其保留为历史记录；迟到的状态绝不会推翻更新的状态。检索也可以考虑时效性（freshness），让多条匹配记录中最新的一条排在最前。
• explainFact：一次调用即可了解相信某项事实的原因——溯源和来源、有效性及其被什么取代、结论的证据及逐条核验的引文，以及历史记录。通过受治理的句柄读取时，若读者无权查看某个来源，会将其标记为已隐去，绝不展示。
• 结论与其依据的事实关联：某项事实不再成立时，基于它得出的结论也会被撤回（但会保留并标记）；某项事实被删除时，基于它构建的一切都会一并删除（SPEC §8a）。
• listConsolidations / undoConsolidation：查看每次处理得出的结论及每条事实的证据，并撤回某次处理得出的结论。撤回会执行失效标记（validTo），并记录撤回每条事实的操作者和原因；绝不删除，因此历史仍会显示曾相信什么、何时撤回以及原因。
• buildSourceProvenance / readSourceProvenance、renderMemoryBlock、exportMemoryMarkdown、衰减辅助函数。
• 集成：al-buddy-memory/ai-sdk（Vercel AI SDK 工具和中间件）、al-buddy-memory/langchain（LangGraph 长期记忆存储和 LangChain 工具）、al-buddy-memory/mastra（输入处理器和工具）。这些框架都是可选的对等依赖项；每次写入都受治理，并会记录执行写入的 Agent。指南见 docs/integrations。

Node ≥ 20。一个运行时依赖（better-sqlite3，为 macOS、Linux 和 Windows 上的 Node 22、24、25 和 26 提供预编译二进制文件；在 Node 20 上会从源码编译，需要 Python 和 C++ 工具链）。Postgres（pg）、MCP SDK 和设备本地模型（transformers.js）都是可选依赖： 只有在使用时才会加载，npm install --omit=optional 会将它们排除。 先行方案：Letta 项目提出了固定记忆层和后台记忆处理的概念（记忆块；休眠时间 Agent）。这里的不同之处在于：每条派生事实都必须引用其依据的原始内容，否则就会被拒绝；原始内容永远不会被改写；整个处理过程都可以审核和撤销，并且撤销操作及其原因都会留档。

import { SqliteMemoryStore, ProjectMemory, PinnedBlocks, exportPortable } from "al-buddy-memory";

const store = new SqliteMemoryStore("./brain.db");
await store.addNode({ provenance: "UserInput", memoryType: "Lesson", content: { text: "Chris prefers decisions over options." }, /* …governance fields… */ });
const pins = new PinnedBlocks(store);
await pins.pin({ text: "Never present options without a recommendation.", label: "rule" });
const snapshot = await exportPortable(/* … */);   // → docs/portable-format.schema.json

完整规范：docs/SPEC.md。设计记录：docs/DECISION-2026-07-07.md。

---

Python 及其他语言

MCP 服务和可移植格式构成了与语言无关的接口：Python Agent 现在就可以使用治理服务，任何语言都可以读取导出内容（它是普通 JSON，带有一个架构）。原生 Python 包已列入计划；如果你希望它提前推出，请提交一个 issue，并说明你会优先用它做什么。

许可证

Apache-2.0。请参阅 LICENSE。

治理靠强制执行，而非默认假定

词汇体系——Public / Private / Sensitive / Sealed、保留期限等级，以及每条事实和关系的来源信息——都随存储一同提供。govern() 负责强制执行：每次写入、更新、读取和导出前都会执行策略，并追加记录谁读取了什么以及原因的审计轨迹。

import { SqliteMemoryStore, govern, personalDefaults, storeAudit } from "al-buddy-memory";

const inner = new SqliteMemoryStore("brain.db");
const store = govern(inner, {
  policies: [personalDefaults({ owner: "chris" })],
  context: () => ({ actor: currentActor() }),
  // The trail goes in the database, hash-chained, in the same transaction as
  // the fact it describes. `new ChainedAudit("audit.jsonl")` puts it in a file
  // instead — for a store that is not SQLite, or when you want it outside the
  // file it describes. See docs/GOVERNANCE.md for what each one proves.
  audit: storeAudit(inner),
});

为确保不会意外擦除任何内容，请将 memoryLock() 添加到策略中：只要它存在，任何人都无法擦除内容，包括所有者，直到你将其移除（或切换它读取的开关）。使事实失效仍然有效；这不属于擦除。原始存储和数据库文件不受任何策略约束，因此请保留备份。

要让删除可以撤销，请向 govern() 传入 recentlyDeleted: { days: 14 }：删除后，事实会在 14 天内从回忆中移除；restoreDeleted 可将其恢复，而 purgeDeleted 会在期限结束后将其永久擦除（再次征询策略，因此锁定仍然有效）。系统不会定时运行；在永久擦除前，事实仍会出现在导出文件和备份中。

使用 al-buddy-memory verify-audit brain.db 检查审计轨迹。它会指出首个被编辑、移除、插入或重新排序的事件。它能证明什么，以及不能证明的两件事，都已写在 docs/GOVERNANCE.md 中——简而言之：这条链具有防篡改迹象；被截断的日志文件尾部对它不可见；只要没有人重置表自身的计数器，被截断的表尾部就能被发现；只有将链头锚定在别处，才能发现链被重写或备份被恢复。

提供了三种策略供复制：个人默认策略（自动将密钥归类为 Sensitive；任何人都不能接触、带走或擦除 Sensitive 事实，只有所有者本人可以；只有所有者可以更改事实）、监护人模式（只有监护人可以写入或更改监护人的事实）、企业审计（对非审核者隐藏低置信度推断；仅允许获准导出者导出）。策略是包含五个可选钩子的普通对象；请参阅 docs/GOVERNANCE.md。

即使没有任何策略，存储仍保证：除非按分类请求，否则 Sealed 事实不会出现在搜索结果中；provenance、nodeId、encryptionKeyRef、原始 content 和锚点轨迹在写入后不可更改，包括通过导入在内的所有路径；所有时间点都以统一规范的 UTC 格式存储。两件它不做的事，也直言不讳地说明：来源信息只是写入者的声明（写入后不可更改，但未经验证——请在策略中将行为者与来源信息绑定）；encryptionKeyRef 指向你管理的密钥，并不会加密文件。

受治理的句柄就是边界。govern(store, …) 会在每项可能更改或披露事实的操作前执行策略——包括擦除，除非策略明确允许，否则会拒绝擦除。持有内部存储的人不受任何治理，因此请交付受治理的存储。

针对使用此记忆的助手所制定的规则已发布在 docs/policies：道德行为、用户自主权与隐私、生命周期与监护人、数据管理责任，以及一份如实记录，说明代码会强制执行什么、提示词会携带什么，以及哪些事情仍由个人决定。这些规则会公开演进。

企业版功能

为组织提供同一个存储：共享数据库、规定谁能看到什么的规则、由运营方控制的加密，以及按请求擦除数据。SQLite 仍是默认选项，这些功能都不会改变本地设置。

• Postgres。 PostgresMemoryStore（pgvector 0.8 或更高版本）位于相同的 MemoryStore 接口之后，并通过相同的一致性测试套件。每次读取和写入都限制在一个租户键内；每次受治理的写入都会在同一事务中为该租户维护审计链；verify-audit --postgres --tenant <key> 可对其进行检查。一次写入仅读取和写入它所操作的行，因此成本不会随租户规模增长：在 1,000 到 100,000 条事实之间测得的耗时保持平稳（使用进程内 PGlite 时，每次写入约 1–3 ms，受治理并记录审计时为 3–6 ms）。 docs/POSTGRES.md
• 边界。 策略可以将谁能看到什么声明为数据：readBoundary 会根据请求方的属性检查事实标签，支持相等、成员关系、AND 和 OR。SQLite 和 Postgres 会将其编译为各自的 WHERE 子句，在排序和任何 limit 之前执行，因此边界之外的事实绝不会占据分页位置。系统会默认拒绝访问，且 beforeRead 仍有最终决定权。docs/policies/boundaries.md
• 登录。 HTTP 服务可以接受来自你自己的身份提供方（Okta、Microsoft Entra、Google Workspace，以及任何 OIDC 颁发方）的 OIDC/JWT bearer 令牌，以代替所有者的密码短语。系统使用 jose 检查签名（颁发方的 JWKS）、颁发方、受众和过期时间；配置的声明会成为边界读取时使用的 Agent 属性，也可以指定一个声明来命名租户。任何检查失败都会返回 401。docs/SIGN-IN.md
• 静态加密不是此库负责的功能。在 Postgres 上，这属于数据库的职责：使用由 KMS 管理的密钥进行存储加密、加密备份以及 TLS。在本地，SQLite 文件是明文的，仅所有者可访问（位于 0700 目录中，权限为 0600），因此请使用全磁盘加密（FileVault、BitLocker、LUKS）。若要进行文件级加密，可以使用 SQLCipher 构建版 SQLite，但此处未构建或测试该版本。encryptionKeyRef 只是为你管理的密钥命名；它不会加密任何内容。
• 擦除。 eraseWhere({ label: "subject", equals: "person-42" }) 会擦除带有该标签且该 Agent 可见的所有事实，以及根据这些事实得出的结论。每条事实都会经过擦除策略，因此内存锁仍会拒绝擦除，“最近删除”仍会保留内容。该调用会返回一份回执，其中包含选择条件、Agent 和时间，以及已擦除、已拒绝（附带原因）和被保留内容的数量；ID 会经过哈希处理。回执摘要会加入审计链，因此 verify-audit memory.db --receipt receipt.json 可以对其进行检查。擦除之前创建的备份和导出内容不在擦除范围内，回执中也会注明这一点。SQLite 和 Postgres 上的行为相同。docs/ERASURE.md

企业版

核心功能始终免费，并采用 Apache-2.0 许可，包括以上所有功能。商业企业版还提供：

• 面向无服务器部署的多进程安全性
• Data API 查询执行器
• 数据库行级安全性
• 企业就绪性测试套件

这些功能接入的扩展点是公开的，读取审计也同样公开：配置 accessAudit: { sink, reads: true } 的 PostgresMemoryStore 会记录租户的每次读取和写入，且记录发生在调用自身的事务中。docs/EXTENSION-POINTS.md

如需咨询，请联系仓库所有者 @flytomoon。

经测量的限制

一个 SQLite 文件、一个进程、一个写入者。在搭载 M1 Pro 的笔记本电脑上，使用 100,000 条 事实（bench/bench.mjs、better-sqlite3、WAL）测得：

操作（100,000 条事实）	测量结果
插入，每次调用一条事实	5,400–5,900 条事实/秒（全部 100k 条需 17–18 秒）
关键词召回，前 10 条（FTS5 + 衰减重排）	中位数为 30–50 毫秒，五个搜索词中最慢约 150 毫秒；打开后首次查询约 320–380 毫秒（冷缓存）
通过受治理句柄进行关键词召回，前 10 条	对出现在 10% 事实中的词约 75 毫秒，对两个这样的词约 135 毫秒，对出现在每条事实中的词约 850 毫秒——见下文
仅按筛选条件召回，前 10 条	0.5–1 毫秒
按 ID 获取	0.1 毫秒
使一条事实失效	0.5 毫秒
重建 snapshotAsOf	有 100,001 个版本时需 2.19 秒
文件大小	100,000 条事实占 69 MB；每条记录的变更增加约 738 字节（对每条事实更新一次后为 140 MB）
在事实自身事务中向 audit_events 写入审计事件	每次受治理写入增加 +0.04 毫秒，每次受治理读取增加 +0.5 毫秒（读取也会审计，因此会短暂获取写锁）
检查链——verify-audit <db>	线性，约 3 微秒/事件：20,000 个事件需 83 毫秒，100,000 个需 325 毫秒，500,000 个需 1.5 秒。每个进程只需检查一次，在首次受治理写入之前进行，且不在写事务内，因此会延迟该进程，但不会阻塞其他进程。内存占用恒定（遍历时流式读取）
轨迹增长速度	每次受治理写入产生一个事件，每次受治理读取产生一到两个事件——一次 remember 增加 2 个，一次 recall 增加 1 个。不会清理任何事件。达到 500,000 个事件时，轨迹约为 128 MB，可能超过其所描述的事实数据；如果存储使用强度如此之高，请留意其大小

范围数据来自 0.4.0 版本中同一脚本的三次运行。分页结果精确：十条记录的一页，是完整有序读取结果中的前十条。当事实确实发生衰减时，为了保证这一点，存储可能需要读取超过 200 行的候选池——最坏情况下会完整读取所有匹配事实（100k 条时约 300 毫秒），而且只有在一条已衰减事实与一条较新的事实原本会互换位置时才会发生。

事务时间测量是在同一台 M1 Pro 上的一次运行：100,000 条事实，每条事实记录一次强化操作，并有一次更早的失效操作。从 100,001 个版本重建全部 100,000 条事实耗时 2.19 秒。这是在内存中进行的线性重建，并非带索引的单点查找。

受治理的关键词搜索速度较慢，这是有意为之。它会读取所有匹配项，保留操作者有权查看的内容，并仅根据这些可见匹配项统计词语稀有度来排名：存储的 BM25 会统计所有事实中的稀有度，包括隐藏事实，因此可能让隐藏事实改变可见结果的顺序。对于个人记忆的规模（几千条事实），速度差异并不明显，而且一项测试验证了其质量：在两百条干扰事实中，用日常问题提问（“wifi 登录信息是什么”）时，相关的十二条事实都出现在第一页。

这意味着：个人助手或单租户服务不会感受到存储带来的影响。托管部署可以使用 PostgresMemoryStore 并显式指定租户密钥； SQLite 仍为默认选项。目前仅支持 Node/TypeScript；可选的设备端嵌入器需要下载一个 25 MB 的模型。

语义路径开销更高

以上内容都是关键词路径。接入嵌入器后，Recall 会进行暴力线性扫描：读取、解码每个已存储的向量，并与查询进行评分。在同一台笔记本电脑上以相同方式测得（bench/bench-vectors.mjs，384 维 float32 向量，与默认设备端模型的维度和数值类型相同）；自 0.8.1 起，向量以 float32 字节形式存储（括号内为 0.8.0 的 JSON 文本数据）：

接入嵌入器	20,000 条事实	100,000 条事实
文件大小（事实 + 向量）	55 MB（172 MB）	277 MB（864 MB）
每个向量的磁盘占用	1,536 字节（约 8,000）	1,536 字节（约 8,000）
语义召回，前 10 条 — 会话中的首次调用	488 ms（765 ms）	1,619 ms（3,200 ms）
语义召回，前 10 条 — 后续调用	中位数 22 ms（36 ms）	中位数 113 ms（187 ms）

gaugeStore 会用这种方式测量任意存储文件，checkBudgets 会指出哪些数值超出预算。

值得保留本节的来龙去脉：2026-09-19，我们测量了 JSON 的开销，提出以 float32 存储作为解决方案，并在此将其列为薄弱环节。六天后，一次关于备份的问题让我们着手实现了它。没有预算的测量只是无人负责的数据，这正是我们创建计量工具的原因。

时间都花在哪儿了，0.8.0 → 0.8.1。 2026-09-19，在 100,000 条事实时，一次冷启动调用花了 978–1,182 ms 读取向量表，花了 1,418–1,744 ms 执行 JSON.parse，而余弦扫描本身只花了 85–127 ms：读取和解析 8 KB 的文本行占了 95% 的开销，大家都怀疑的扫描只占 4%。改为存储 float32 字节后，读取耗时缩短了约 5 倍，也省去了解析；首次调用剩余的 1.6 秒耗时，是在读取 154 MB 数据并将其转换为 JavaScript 数组。由此带来两个结论：

• 以当前规模来看，sqlite-vec 仍不是下一步的选择；扫描并非开销所在。
• 向量缓存可以丢弃，并且与模型绑定。 向量存储在独立的表中，以 (nodeId, model) 为键；删除它们只会增加耗时，来自不同模型的向量会被跳过，而不会拿来比较。升级嵌入器意味着重新索引，而不是迁移。

扫描仍会随着事实数量线性增长，而会话中的首次调用要处理整个向量表；后续调用会复用 60 秒的进程内缓存。

备份、恢复与同步文件夹

WAL 模式下的 SQLite 数据库由三个文件组成：brain.db、brain.db-wal、brain.db-shm。两种常见操作可能会悄无声息地丢失某人的记忆：

• 恢复备份： 先停止服务，再删除 brain.db-wal 和 brain.db-shm，然后将备份复制到位。若恢复后的文件旁还留有 -wal 文件，下次打开时会将其重放到恢复文件之上，因此恢复看似成功、不会报告错误，却留下了你原本想要替换的数据。已于 2026-09-19 验证。
• 选择哪种备份命令： sqlite3 brain.db ".backup out.db" 和 VACUUM INTO 'out.db' 都是安全的——两者都能对正在运行的数据库生成一致的快照，且已在另一个进程同时写入时验证过。sqlite3 .dump 也可用，但不会保留 user_version；在 0.4.2 之前，恢复的转储文件根本无法打开（duplicate column name: valid_from），现在则可以顺利迁移。切勿通过对正在运行的数据库执行 cp 来备份：写入期间复制的文件可能无法读取，即使能读取，也仍可能无法通过 PRAGMA integrity_check。
• 同步文件夹： 切勿将数据库放在 iCloud、Dropbox、OneDrive 或 Google Drive 中。WAL 模式假定由一台机器协调自身的锁；同步客户端若分别复制这三个文件，或两台机器通过同一个文件夹写入，就会损坏文件，而不是产生明显的冲突。你当然可以备份整个文件夹——按计划将其复制到其他位置，或使用 .backup/VACUUM INTO——但不要让同步客户端管理正在使用的文件。

一致性评分

试试看：albuddy.com — 粘贴任意记忆导出内容，数据不会离开你的浏览器。

回忆基准测试已趋于饱和。没人会评估记忆系统能否说清楚一条事实是由谁提出的、从何时起成立、现在是否仍然成立，以及这条事实能否在离开供应商后保留下来。本工具会对你粘贴的任意导出内容评估这些方面：

npx al-buddy-memory conformance my-export.json          # format auto-detected
npx al-buddy-memory conformance agent.af --format blocks     # block-style agent files
npx al-buddy-memory conformance memories.json --format records  # flat memory records
npx al-buddy-memory conformance --demo                  # a small governed store, for comparison

七个维度，每项 0–100%，并明确说明原因；如果样本无法证明某个维度（比如其中没有已退役的事实），该维度会标记为未证实，并从总分中排除，而不是计为不合格。参考评分：

导出内容	来源信息	起始时间	退役但不抹除	置信度	关系	可移植性	等级
al-buddy-memory（演示存储）	100%	100%	100%	100%	100%	100%	A

用同样的方式为你自己的导出内容评分：对于块状 Agent 文件，使用 --format blocks；对于扁平记忆记录，使用 --format records；或者将内容粘贴到 albuddy.com 的演示页面中。

下面直截了当地说明这些数字的来源，因为我们也会用这套评分器评估自己。七项中的五项——来源信息、起始时间、退役但不抹除、置信度、关系——根据你粘贴文件中的记录计算；更改样本，这些分数也会随之变化。**另外两项不是。**系统是否保留已退役的事实、是否公开其架构，以及是否逐项列出事实，都是系统的属性，单次导出无法证明。因此，适配器作者会在 src/conformance/adapters.ts 中声明这些属性，它们会原样显示在报告的原因说明中。唯一通过实际执行而非声明来验证的部分是往返测试：对于我们自己的格式，评分器会将你的文件导入一个全新的存储，再次导出并进行比较——测试的就是你的文件；如果失败，结果会显示 lossy。

评分规则手册说明了各维度的含义，以及评分不衡量哪些方面（回忆质量、真实性、延迟），请参阅 docs/SCORING.md。适配器基于导出的结构编写，而非特定供应商。如果某个系统开始记录来源信息，它的评分就会提高——这正是我们的目的。为你的结构添加一个适配器并提交 PR；如果你认为我们对其某项特征的声明有误，也可以提交一个仅改一行的 PR。

基准测试

一致性评分衡量的是召回基准测试未涵盖的内容；它不会取代这些基准测试。bench/ 中的两个测试框架为其提供了量化数据，每项结果的文件、提交和设置均列于 bench/results/：

• LongMemEval，公开的召回基准测试：针对聊天历史中的 500 个问题，每段历史约包含 50 次会话。每个问题都会使用一个全新的存储，其中通过公开 API 为每条消息存储一条记忆，不进行任何提取或摘要；召回决定读者能看到什么。读者和评判者的提示词、是非判断规则以及检索指标均采用官方版本，并通过测试确保与官方代码一致。读者和评判者均为 Claude，通过 Claude Code CLI 使用订阅运行，因此运行不会产生按量计费的 API 费用——但评判者因此不是官方的 gpt-4o，这也是每项结果都附带官方格式答案、供任何人重新评判的原因。node bench/longmemeval/run.mjs --limit 50 是一次冒烟测试。最新的完整运行（2026-09-30，全部 500 个问题，不使用重排器）：总体 92.6%，按任务平均 94.4%，笔记本电脑上的召回调用本身为 p50 11.7 ms / p95 33.5 ms——与 bench/results/README.md 中启用所有选项的运行结果并列展示。使用官方评判者（gpt-4o-2024-08-06、官方提示词、温度 0）重新评分：总体 92.8%，按任务平均 94.4%——这是与其他系统比较时应参考的数字；Claude 评判者给出的结果为 92.6% / 94.4%。
• 过时事实，我们自己的基准测试：关于某个人、会随时间变化的信息，以三种方式告知同一个存储——仅追加、仅追加并在召回时考虑时效性，以及通过 recordState 记录；后一种方式中，较新的状态会关闭旧状态。测试会询问召回是否返回当前为真的值，以及过去某个时刻为真的值。不会调用任何模型；结果是确定性的。

过时事实的测量结果（结果；24 个关于当前的问题，11 个关于过去某个时刻的问题；关键词召回，不使用嵌入器；前 5 条结果）：

	仅追加	仅追加 + 时效性	recordState
现在：过时的值排在第一位	50.0%	4.2%	0.0%
现在：前 5 条中包含过时的值	87.5%	37.5%	0.0%
现在：当前的值排在第一位	16.7%	25.0%	33.3%
当时：前 5 条中包含当时并非真实的值	27.3%	27.3%	18.2%
当时：当时真实的值排在第一位	27.3%	9.1%	27.3%

请按实际情况理解这些结果。只有失效处理才能将过时答案排除在外：在仅追加的存储中，半数“情况如何”的问题会将旧值放在第一位。时效性会隐藏旧值，却不会将其移除——旧值仍有超过三分之一的概率出现在前 5 条中——而且它会把晚些时候提到的旧事实误认为新事实：当被问及我开什么车时，它会回答最后提到的 2019 款 Civic。对于所有策略而言，当前值最多也只有三分之一的概率排在第一位，这反映了关键词召回的局限：较短的问题（“我有什么手机？”）会与无关事实中的稀有词匹配，而“我接受了 Cobalt Robotics 的录用通知”与“我在哪里工作？”只有“I”一词重合。recordState 仍会显示错误值的两个过去时刻问题，揭示了这项基准测试发现的一个缺口：较晚获知的状态会在下一个仍有效的状态出现时关闭，而不是在时间上紧随其后的状态出现时关闭，因此，晚于 2025 年住所提及的 2018 年住所会被视为仍然有效，与中间的住所并存。

治理 MCP 服务

大多数记忆 MCP 服务会把一条事实交给 Agent。 这个服务交给它的是一条可以权衡的事实：每条 recall 结果都带有 provenance、 validFrom、validTo、current、confidence、写入它的助手和将它退役的助手，以及——对于已被取代的事实——取代它的事实 ID。invalidate 会关闭事实的有效期并保留记录；服务没有擦除工具。它提供的是受治理的存储：所有者的 personalDefaults，受众为 AI 客户端。因此，Agent 写入的秘密会被归类为敏感信息，并排除在任何 AI 的召回结果之外；每次调用都会经过审计——写入数据库本身，并与事实在同一事务中完成。

{ "mcpServers": { "memory": { "command": "npx",
    "args": ["-y", "[email protected]", "al-buddy-memory-mcp"] } } }

al-buddy-memory-mcp 是 al-buddy-memory 包内部的可执行程序，并非独立包，因此 --package= 用来告诉 npx 去哪里查找它——npx al-buddy-memory-mcp 会查找同名包，结果得到 404。去掉 @0.12.0 即可跟踪最新版本，而不是使用你测试过的版本。

准备发布？ 这个固定版本号是有文档记录的版本；一旦发布新版本，它就会过时——届时这个示例安装的服务会比页面所描述的旧。 请在提升版本号的同一个提交中更新它——0.4.2 和 0.5.0 都是如此；0.4.1 发布期间，它曾是 @0.4.1。对较新版本运行固定版本命令，会返回旧服务的握手信息；读者因此会看到与刚安装内容不符的文档（Astra 发布审核，2026-09-19）。

记忆会存放在 ~/.al-buddy-memory/brain.db；设置 AL_BUDDY_MEMORY_DB 可将其放到其他位置。请使用绝对路径——JSON 配置不是 shell，其中的 ~ 会由此服务展开，但其他可能读取该值的程序未必会展开。 审计记录会写入该数据库的 audit_events，并与其描述的事实在同一事务中追加——无论运行多少个助手，都共用一条哈希链。使用 al-buddy-memory verify-audit ~/.al-buddy-memory/brain.db 检查。早于该表的服务会在 brain.db.audit/ 中为每个进程分别保存一份日志；更早的版本则使用单个 brain.db.audit.jsonl 文件；这些记录既不会被接纳，也不会被续写（它们证明的是表无法证明的时期，反之亦然），同一命令会连同该表一起报告这些记录。AL_BUDDY_MEMORY_AUDIT 仍可指定要使用的 JSONL 文件——如果这样做，每个文件仅供一个进程使用。

recall 结果如下所示——其中每个字段都能帮助 Agent 判断该事实有多可信：

{ "id": "…", "text": "Lives in Tokyo", "provenance": "UserInput", "validFrom": "2026-06-01T00:00:00Z",
  "validTo": null, "current": true, "confidence": 1, "supersededBy": null, "derivedFrom": [],
  "recordedAt": "2026-06-01T00:00:00Z",
  "origin": { "app": "claude-desktop", "appVersion": "1.2.3", "via": "mcp" }, "retiredBy": null }

origin 是写入事实的助手，取自 MCP 握手，而非模型；retiredBy 则是关闭该事实的助手——因此，在助手真正共享的记忆中，已退役的事实是一件带有执行者的事件。如果宿主不知道相关信息，这两个字段都为 null。

**remember 会回答“这条事实可能会取代什么？”**它会返回存储的事实，以及 mayConflictWith：最多三个与新事实读起来相似的当前事实，每条都包含其 ID、文本和 validFrom。

{ "id": "…", "text": "Lives in Berlin", "…": "…",
  "mayConflictWith": [ { "id": "…", "text": "Lives in Tokyo", "validFrom": "2026-06-01T00:00:00Z" } ] }

不会自动退役任何事实——客户端会读取这些事实，并对不再成立的事实调用 invalidate。这就是完整的“失效而非覆盖”循环；在 0.4.2 之前，界面中没有任何内容会提示客户端执行此操作。请将列表视为要读取的事实：它们是最佳的词法匹配项，而非已证实的冲突。

每个连接的第一次 recall 还会将固定层级——即此人的常设规则——作为第二个内容块返回，因此，声称会出现在每条提示词中的层级无需占用握手的 512 个字符，就能传递到位。 工具：remember、recall、history、explain、invalidate、pin、unpin、pinned、mental_model、define_mental_model、export，以及用于团队记忆的 promote 和 withdraw（个人服务的策略会拒绝这些操作；参见 docs/policies/scopes.md）。mental_model 会读取某个常设问题的预写答案，并提供其时效性和依据（宿主会按自己的计划刷新答案）。explain 会说明某条事实为何可信：是谁提出的、何时为真、是什么使其失效；对于结论，还会说明其依据的确切原文，并在当前逐一核查。remember 最多接受 4,000 个字符，pin 最多接受 500 个字符；recall 查询最多 1,000 个字符，invalidate 原因最多 500 个字符，ID 最多 128 个字符。pin 会拒绝看起来像机密的文本，因为服务会将其存储为 Sensitive，任何助手都无法查看。invalidate 的 replacedBy 必须指定调用方可见的事实。SQLite 存储在磁盘上，无需服务或密钥。工具函数是针对 MemoryStore 的普通函数（从 al-buddy-memory/mcp 导出的 governanceTools(...)），因此可在任何后端上运行，并且无需传输层即可测试；其中的 pin 需要设置 pinning: true，这仅应由运行在用户自己机器上的宿主传入。

召回采用混合方式——结合关键词和语义，并读取查询中的时间和计数提示（expand）；LongMemEval 结果就是在此设置下测得的。服务会立即启动关键词召回，同时在本机加载嵌入模型；模型加载完成后的调用会同时使用两种方式。模型（all-MiniLM-L6-v2，约 90 MB）会从 Hugging Face hub 下载一次到 ~/.al-buddy-memory/models（可通过 AL_BUDDY_MEMORY_MODEL_CACHE 更改此路径），之后即可离线运行；在模型就绪前存储的事实会在后台生成嵌入，每次启动最多处理 5,000 条（AL_BUDDY_MEMORY_INDEX_LIMIT）。如果无法加载模型——例如未安装 @huggingface/transformers、平台没有可用的 onnxruntime 二进制文件（例如 Intel Mac），或首次运行时没有网络——召回将仅使用关键词，服务会在 stderr 上说明一次。模型会在工作线程中加载和运行，后台处理每隔 20 ms 就会将事件循环的控制权交还，因此服务在建立索引期间仍可响应。AL_BUDDY_MEMORY_SEMANTIC=off 时，模型不会加载。交叉编码器重排器尚未启用：在完整的 LongMemEval 测试中，它对总分毫无影响（启用和未启用均为 92.6%），却需要额外的模型。

导出。 export 工具会以可移植格式返回记忆——小于 50 KB 时直接内嵌返回，否则写入你指定的绝对 .json 路径（该路径必须尚不存在；工具绝不会覆盖文件）。它会导出助手能够召回的内容：策略会排除 Sensitive 和 Sealed 事实。包含所有事实的完整备份由命令行负责，导入也可通过命令行恢复：

al-buddy-memory export --out ~/memory-backup.json        # or --format markdown for a readable mirror
al-buddy-memory import ~/memory-backup.json              # checks the whole file first; safe to re-run

两者都会像服务一样读取 AL_BUDDY_MEMORY_DB（或 --db）。al-buddy-memory context 会打印 Claude Code 插件在会话开始时显示的简短简报；al-buddy-memory status 则会打印各项计数、数据库路径、最近一次写入时间，以及语义搜索是否可用。

在 Claude 和 ChatGPT 中作为远程连接器

al-buddy-memory-http 通过 Streamable HTTP 为单个所有者提供相同的工具，并使用 OAuth 2.1（PKCE S256、动态客户端注册、轮换刷新令牌）登录。每个工具都声明了 title、readOnlyHint、destructiveHint 和 openWorldHint，这是两个助手目录都要求的注释。它监听 127.0.0.1；在前面配置一个隧道（例如 tailscale funnel --bg --https=8443 http://127.0.0.1:8787），然后向应用提供其 URL：

echo 'a long passphrase' | al-buddy-memory-http --set-passphrase   # stores a scrypt hash, 0600
AL_BUDDY_MEMORY_PUBLIC_URL=https://you.example.ts.net:8443 al-buddy-memory-http

在 Claude 中：Customize → Connectors → Add custom connector，URL 为 https://…:8443/mcp。在 ChatGPT 中：进入 Settings → Security and login → Developer mode，然后添加相同的 URL。每个应用都会打开一次授权页面；输入密码即可授权。磁盘上只会保存代码和令牌的哈希值。某个应用输错密码 5 次，该应用会被锁定 15 分钟；所有应用在 15 分钟内累计输错 20 次，则所有应用都会被锁定；每次锁定都会记录日志。应用写入的事实会将其注册名称（也是授权页面显示的名称）记录为该事实的 origin，每次调用的审计事件也会标明该名称。有两项操作仅限在本机执行：export 会直接返回结果，不会写入文件；pin 则会被拒绝，因为固定规则会随每个助手的提示词一起发送。请在本地服务中通过助手固定规则（al-buddy-memory mcp）；远程应用登录后，首次调用 recall 时会获取这些规则，规则更改后再次调用时也会获取更新后的规则。对于组织，可改用自己的身份提供商登录同一服务：docs/SIGN-IN.md。

将其用作 Claude Code 插件

此仓库也是 Claude Code 插件市场。在 Claude Code 中：

/plugin marketplace add flytomoon/al-buddy-memory
/plugin install al-buddy@al-buddy

也可以在 shell 中运行 claude plugin marketplace add flytomoon/al-buddy-memory 和 claude plugin install al-buddy@al-buddy。无需进行任何配置。入门指南、命令和故障排查：见 docs/claude-plugin.md（以及 albuddy.com/claude.html）；隐私说明：见 docs/PRIVACY.md。

所有命令均位于插件的 al-buddy: 命名空间下：/al-buddy:recall <question>、 /al-buddy:remember <fact>、/al-buddy:forget <fact>（将其设为退役状态；保留在历史记录中）、 /al-buddy:status、/al-buddy:export [file]、/al-buddy:import <file> 和 /al-buddy:help。

此插件（plugin/）提供：

• 上文所述的治理 MCP 服务，通过 npx 启动，并固定到确切版本；首次启动会下载软件包（安装后约 500 MB，其中大部分是可选的模型运行时）；
• 两项技能：recall（在回答有关过往工作、决策、人员或偏好的问题前搜索记忆）和 remember（存储长期有效的事实——绝不存储机密、凭据或闲聊内容）；
• SessionStart 钩子，会在会话开始、清除或压缩时添加一段不超过 2,000 个字符的简报：你的固定规则、提及项目文件夹名称的事实，以及最近学到的事实，并且仅包含助手获准查看的内容。它不会自行安装任何内容，因此在服务器首次安装期间启动的首个会话不会收到简报。

数据存储位置。 ~/.al-buddy-memory/brain.db，在服务器首次启动时创建；若要将其存放在其他位置，请在 Claude Code 启动时所处的环境中将 AL_BUDDY_MEMORY_DB 设为绝对路径。嵌入模型存放在其旁边的 ~/.al-buddy-memory/models 中。除两项一次性下载（npm 软件包和模型）外，不会有任何数据离开本机。

导出、备份和移除。 可让 Claude 导出你的记忆（使用 export 工具），或运行 al-buddy-memory export --out <file>.json，创建完整的所有者备份。卸载插件 （/plugin uninstall al-buddy@al-buddy）不会删除你的记忆；若要将其移除，请删除 ~/.al-buddy-memory/，如需保留记忆，请先导出。

Claude 桌面应用。 从下一次发布开始，每个 GitHub release 都会附带一键安装扩展 al-buddy-memory.mcpb（macOS），由 npm run build:mcpb 构建。它包含服务器及其依赖项，包括为 Claude Desktop 内置的 Node.js 编译的 SQLite 引擎，并且使用与插件相同的 ~/.al-buddy-memory/brain.db，因此两个应用共享同一份记忆。操作步骤见 docs/claude-plugin.md。

Claude Code 以外的宿主。 插件使用的就是同一个服务器：任何 MCP 客户端都可以使用 治理 MCP 服务中的 npx 配置。Codex 和 ChatGPT 桌面应用共用一份配置；在 shell 中运行 codex mcp add al-buddy-memory -- npx -y al-buddy-memory mcp，或者在桌面应用中依次选择 Settings → MCP servers → Add server → STDIO，并使用该命令。详情见 docs/claude-plugin.md。

al-buddy-memory status 会打印当前、已退役和已固定事实的数量、数据库位置、上次写入时间，以及此机器是否能够运行语义搜索（仅统计信息）。

需要 PATH 中有 Node.js 22 或更高版本；只有在 better-sqlite3 能从源代码编译的环境中，Node 20 才可用（它不附带 Node 20 二进制文件）。

在 Claude 应用中实现自动记忆

在 Claude 桌面应用中，以及通过远程连接器在网页或手机上，只需粘贴一次，即可始终开启捕获：Claude 会自动保存每次有实质内容的对话，不必等你提出要求——包括问题、答案或建议及其理由，以及最终决定。说“记住”只会让它立即保存。在应用的设置中，将以下内容粘贴到 Claude 询问你的个人偏好之处（即它在每次聊天中都会遵循的指令）：

Use Al Buddy memory automatically, without being asked. At the start of each conversation, call recall for my pinned rules and anything relevant. After each exchange that has any substance, save it with remember: the date, what I asked or said, what you answered or recommended and why, and what we decided. Mark my own words as UserInput and your answers or recommendations as AIInferred. Save the substance and the reasoning, not filler or small talk. If I say remember, save it right away. Never save secrets or passwords. When something earlier stops being true, invalidate it instead of saving a contradiction.

然后，在应用设置 Al Buddy 工具权限时（或应用首次询问是否使用工具时），将 recall 和 remember 设为无需每次询问即可运行；而 invalidate、unpin 和任何会擦除数据的工具，都应保留为先询问你的设置。

原因：在 Claude 应用中，只有在有指令触发时才会使用连接器，而且没有钩子能自动捕获对话——在我们 2026 年 10 月 11 日的测试中，即使已设置服务自身的指令，Claude 也只会在收到要求时保存记忆。这条指令才能让捕获持续运行。相同步骤也提供了复制按钮：albuddy.com/claude.html。

路线图

• 发布并进行版本控制的规范与可移植格式（本仓库）
• al-buddy-memory conformance <export>：根据来源追溯、失效处理和可移植性，对任意记忆导出进行评分，并提供适配器以支持块式 Agent 文件和平面记忆记录（v0.2.0）
• 治理型 MCP 服务：为每条事实返回来源追溯信息和有效性状态的记忆服务（v0.2.0）
• 治理钩子，带有审计追踪和三种示例策略；运行时来源追溯信息不可变；在 100k 条事实规模下测得性能限制（v0.3.0）
• 审计事件与其描述的事实在同一事务中提交，形成供多个进程共享的一条链（v0.4.2）
• 对比表和可在线试用的粘贴导出内容演示（albuddy.com）
• 事务时间，即双时态的另一半：“在 X 时我们认为是什么”，包括一条当时持有但后来证实错误并得到更正的事实（v0.5.0）
• 在同一 MemoryStore 接口下提供 Postgres 后端，适用于多租户和托管部署（SQLite 仍是本地优先的默认选项；该后端会运行共享的一致性测试套件）
• 框架集成：Vercel AI SDK、LangChain/LangGraph、Mastra（v0.7.0）

开发

npm ci
npm run check   # typecheck, tests, and the browser bundle — exactly what CI runs

测试包含一套行为一致性测试套件，每个后端都会针对自身运行该套件。