ai-memory — Persistent Memory for Any AI

ai-memory

通用 AI 记忆

ai-memory 是一套面向 AI 助手的持久化记忆系统。它适用于任何支持 MCP 的 AI——Claude、ChatGPT、Grok、Llama 等。它会将 AI 学到的内容存储在本地 SQLite 数据库中，回忆时按相关性排列记忆，并自动将重要知识提升为永久存储。只需安装一次，你使用的每个 AI 助手都能永远记住你的架构、偏好和纠正内容。

选择安装方式

正在配置 LLM 后端（xAI Grok、OpenAI、Anthropic、Gemini、DeepSeek、Kimi、Qwen、Mistral、Groq、Together、Cerebras、OpenRouter、Fireworks、LMStudio、vLLM、llama.cpp server 或本地 Ollama）？请参阅 docs/integrations/llm-backends.md — 无论采用哪种安装方式，MCP 环境变量代码块的配置方法都相同。

v0.9.0 — 当前版本。 这是一个安全加固与代码审查版本：经过 5 个方向的对抗性审查后修复了 49 个问题（#1885–#1935），并新增了少量功能。最重要的变化是切换为安全默认设置：HTTP 直接写入默认要求 Agent 证明（#1751，由 #1985 按调用面限定）——未签名的 HTTP POST /api/v1/memories（以及 POST /bulk）会被拒绝（403 ATTESTATION_FAILED），而不是写入 attest_level="claimed"；除非操作员显式选择退出，设置 AI_MEMORY_REQUIRE_AGENT_ATTESTATION=0。MCP memory_store 和 CLI store 调用面采用操作员作为执行者的路径，默认仍然宽松（未签名的写入会写入 claimed）；设置 =1 则会在所有调用面强制启用严格模式。（v0.9.0 GA 版本曾要求所有调用面都进行证明，这在 MCP 主机上无法实现；当前版本已修正为按调用面限定。）此外，强制 Hook 存在性执行门现在同时作用于 MCP 写入路径（#1885）和 HTTP 写入路径（#1924），堵住了一个静默绕过漏洞：已配置的强制 Hook 可能在一个调用面被跳过，而在另一个调用面正常执行。此次加固还完善了 bulk_create 逐行证明门控（#1919），使入站联邦 PENDING 审批经过已注册审批人的门控（#1920），收紧 team/unit/org 可见性范围，避免其在命名空间层级中范围过宽（#1921），并通过符号链接隔离，确保 skill_register 的 folder_path 导入仅限于配置的根目录下（#1923）。新增了非 argv 凭证通道 — AI_MEMORY_STORE_URL / AI_MEMORY_STORE_URL_FILE（一个权限为 0600 的文件）— 防止 postgres/store 密码出现在任何用户都可读取的 /proc/<pid>/cmdline 和 ps 中（#1927）。新增功能包括：由 Agent 编写的技能记忆，支持 parameters_schema 和 invocation_record（B7-SKILL，#1865）；recall_observations 影子反馈循环（#1706）；记忆派生谱系 DAG（memory_lineage，#1859）；以及可选启用的 vector-search 最小功能集（#1005）。版本概况：架构 v78；--profile full 下有 101 个 MCP 工具（100 个可调用工具 + 始终启用的 memory_capabilities 引导工具），--profile core 下有 7 个；92 个 HTTP 路由注册（78 个唯一 URL 路径）；在 --features sal/sal-postgres 下有 89 个类型化 CLI 子命令（默认构建中为 87 个）；9 种类型化 MemoryLink 关系；Memory 有 28 个字段。支持两种生产后端，通过完全相同的 API 提供服务 — 嵌入式 SQLite 和 PostgreSQL + Apache AGE — 覆盖桌面端、服务端和设备端（iOS + Android）。除证明和 Hook 执行策略的切换（两者都是安全优先的破坏性变更）外，其余均为 v0.8.1 之上的增量更新 — 升级前请先仔细审查这些变更。完整变更日志： CHANGELOG.md §"[0.9.0] — 2026-07-08"。 v0.8.0（distributed-coordination）— 上一版本。 在此版本中，记忆底层架构升级为协调底层架构。它引入了来自 #1709 的分布式协调机制：带有真正状态机的类型化操作 DAG（memory_action_*）、有 TTL 限制的单持有者租约（memory_lease_*）、Ed25519 签名信号（memory_signal_*）、Ed25519 证明检查点（memory_checkpoint_*），以及冻结且可重放的例程（memory_routine_*）——让异构 Agent 集群可以轮流工作、移交任务，并证明是谁说了什么，而无须彼此信任。在此基础上，它还加入了类型化认知（Goal/Plan/Step 记忆类型、lifecycle_state 状态机，以及 decomposes_into / depends_on / advances 链接关系）、强化联邦机制的默认安全性（默认启用对等节点注册 #1789、为每次状态转换签名 #1718、为每次写入进行内容证明 #1464、状态转换重放随机数 #1805、出站对等节点证书固定 #1678），并提供了真正具有阻止作用的治理机制——Claude Code PreToolUse hook 已改为 type:command 包装器，因此底层架构的 Refuse 确实会拒绝工具调用（#1811）。v0.8.0 发布时，项目概况如下：schema v70，--profile full 下有 100 个 MCP 工具（99 个可调用工具 + 始终启用的 memory_capabilities 引导工具），--profile core 下有 7 个工具，91 个 HTTP 路由注册项（78 个唯一 URL 路径），83/85 个 CLI 子命令，9 种类型化 MemoryLink 关系，以及包含 27 个字段的 Memory。可在桌面端、服务端和设备端（iOS + Android）上运行，底层采用两个生产级后端，但提供完全相同的 API——嵌入式 SQLite 和 PostgreSQL + Apache AGE。所有更改均在 v0.7.0 基础上增量添加；升级前请检查默认安全设置的变化。完整发行说明：docs/v0.8.0/release-notes.md。 v0.7.0（attested-cortex）——上一版本。 汇集了 cortex-fluent 易读性改进，以及 ROADMAP §7.3 中完整的 v0.7 信任与 A2A 范围，此外（根据运营方 2026-05-09 的指令）还纳入了原计划在 v0.7.1 推出的 postgres+AGE 一等支持工作，以及 grand-slam 发布后的就绪度提升工作（Batman Forms 1-6 + 第 7 种表单的 Option-B 基础 + QW-1/2/3 + 对账安全审查）。底层既变得更善于表达（capabilities v3、具名加载器工具、精简的架构、Batman MemoryKind 词汇、persona/原子化/多步摄取基础能力），又变得具备密码学可信度（Ed25519 证明、sidechain 转录、可编程的 25-event 钩子管线、强制命名空间继承、V-4 跨行签名事件哈希链）。v0.7.0 还将 postgres + Apache AGE 作为一等存储后端推出——实时守护进程可使用 ai-memory serve --store-url postgres://…，两个后端的架构保持一致（在 v0.7.0 发布时，sqlite + postgres 收敛到逻辑架构 v57，其中 CURRENT_SCHEMA_VERSION 为 57；v0.8.0 发布版底层已将这一锁步版本推进至架构 70，两个后端均已加入增量式 v58–v70 协调与可见性表——有关 v58–v70 版本阶梯，请参阅 CLAUDE.md §Database）（权威锚点：sqlite 的 src/storage/migrations.rs + postgres 的 src/store/postgres.rs）；磁盘上的迁移文件截止于 migrations/sqlite/0047_v56_list_composite_indexes.sql，postgres 的进程内 migrate_v57() 版本阶梯分支也截止于 v57（文件名计数落后于逻辑架构版本，因为两个版本阶梯都通过进程内分支应用 v34 之后的增量——v35-v57 的说明请参阅 docs/MIGRATION_v0.7.md §schema-ladder；v48 #933 新增 federation-push 死信队列表；v49 #1025 向 archived_memories 新增 14 个可空列，使归档 → 恢复能无损保留完整的 v0.7.0 Memory 形态；v50 #1156 将 agent_quotas PRIMARY KEY 从 (agent_id) 扩展为 (agent_id, namespace)，确保单个 Agent 跨多个命名空间运行时，每个命名空间的 K8 配额分配仍然有效——v50 之前的行回填到 _global 哨兵命名空间；v51 #1255（PR #1296）新增 federation_nonce_cache 表，使对等端重放防护 nonce 在守护进程重启后仍能持久保存；v52 #1389 新增 transcript_line_dedup 表，为 RFC-0001 memory_capture_turn L4 + recover_from_transcript L2 幂等性提供支持，确保两轮之间发生 SIGKILL 后，后续重新水合不会产生重复记忆；v53 #1418 将 memories_au FTS5 同步触发器限定为仅作用于 (title, content, tags)，从而不再因更新非 FTS 列而触发不必要的同步；v54 #1466 为旧版 NULL 到期时间的中/短期行回填层级默认到期时间，以解决 TTL 泄漏导致行永久存在的问题；v55 #1476 使 W=2 联邦追赶查询（updated_at > ? ORDER BY updated_at ASC LIMIT）具备可搜索参数能力，并新增 sqlite idx_memories_updated_at 索引——postgres 不新增索引，因为 memories_updated_at_idx DESC 已可通过 Index Scan Backward 服务于范围扫描；v56 #1579 新增列表/归档排序复合索引（idx_memories_list_order、idx_memories_ns_list_order、idx_archived_ns_archived_at），并配合具备可搜索参数能力的 storage::list 重写——仅涉及 sqlite 端 DDL；postgres 的 migrate_v56() 分支为空操作，仅更新版本戳；v57 #1579 新增 postgres 存储生成列 tsv tsvector 和 memories_tsv_gin GIN 索引，使搜索/回忆查询形态保持一致，且基于预计算列进行排序，而非针对每个匹配行重新计算 tsvector——旧版 memories_content_fts 表达式索引已删除，sqlite 对应版本为空操作，仅更新版本戳，因为 FTS5 已经物化了索引文本），新增 ai-memory schema-init CLI 子命令，以及 6 因素回忆评分一致性。v0.6.4 的默认接口新增两个常驻加载器，工具总数达到 7 个（memory_load_family + memory_smart_load 加入原有的五个工具）；--profile full 下的运行时上限为 74 个已公布条目（73 个可调用的记忆工具 + 常驻的 memory_capabilities 引导工具；已通过 Profile::full().expected_tool_count() 验证——参见 src/profile.rs）。所有新增内容均为增量式功能，且（对于信任与 postgres 功能）默认选择启用。从 v0.6.x 升级？ 请先阅读 docs/MIGRATION_v0.7.md——大多数 v0.6.4 调用方不会看到行为变化，但 v0.6.3.1 之前的 v0.6.x 用户会受到 G1 命名空间继承修复的影响。切换到 postgres+AGE？ 请参阅 docs/postgres-age-guide.md 和 docs/migration-v0.7.0-postgres.md。完整发行说明： docs/v0.7.0/release-notes.md。 v0.6.4（quiet-tools） — MCP 服务默认提供 5 个工具（memory_store、memory_recall、memory_list、memory_get、memory_search），并始终启用 memory_capabilities 引导工具。其余 38 个工具仍可通过 --profile graph|admin|power|full 或运行时使用 memory_capabilities --include-schema family=<name> 扩展来调用。急切加载工具的运行环境（Claude Desktop / Codex CLI / Grok CLI / Gemini CLI）每次请求可减少约 4,700 个输入令牌的工具架构开销——根据 cl100k_base BPE 测量，减少 76.4%。如需完整保留 v0.6.3 的行为，请运行 ai-memory mcp --profile full。参见 docs/MIGRATION_v0.6.4.md。

v0.9 新增内容

v0.9.0 主要是一个安全加固和代码审查版本——通过 5 条审查路径进行对抗性审查，修复了 49 个问题（#1885–#1935）——此外，还在 v0.8.0 协调基础之上添加了一小批功能。完整更新日志：CHANGELOG.md §“[0.9.0] — 2026-07-08”。

默认安全加固

• 默认要求 HTTP 直接写入接口提供 Agent 证明（#1751，由 #1985 按接口范围限定）。AI_MEMORY_REQUIRE_AGENT_ATTESTATION 为三态配置，并针对不同接口采用编译时默认值：未设置 → HTTP 直接写入（POST /api/v1/memories + /bulk）必须提供证明（否则返回 403 ATTESTATION_FAILED）；MCP memory_store 和 CLI store 的操作员作为执行者接口则为宽松模式（未签名的写入会以 attest_level="claimed" 落库）；=1 会在所有接口强制严格校验，=0 会在所有接口强制宽松模式。无论使用哪个接口，提供但伪造的签名都会被拒绝。请为写入签名（ai-memory store --sign，并使用通过 ai-memory agents bind-key 绑定的密钥对），或使用 =0 选择退出。（v0.9.0 GA 版本曾要求所有接口都提供证明，在 MCP 主机上无法满足——见 #1981；随后通过 #1985 修正为按接口范围限定。）
• MCP 和 HTTP 双重钩子强制门控（#1885 / #1924）。现在 HTTP 写入路径也会检查强制钩子是否存在的门控（最初仅适用于 MCP，见 #1734），从而堵住了可静默绕过的漏洞（CWE-288）：完全跳过 MCP 的写入请求此前不会检查是否配置了强制钩子。
• bulk_create 证明门控（#1919）。批量写入现在会像单次 memory_store 调用一样，按行强制要求 Agent 证明——批次中的每一行都必须携带有效证明，而不只是整个请求携带证明。
• 联邦审批者门控（#1920）。只有在传入的联邦 PENDING 审批归属于对等方已注册的审批者时，才会予以认可；已加入但不受信任的对等方无法再伪造对任意请求者的审批。
• team/unit/org 范围加固（#1921）。可见性范围解析现在会针对 team/unit/org 范围正确强制执行命名空间祖先层级，从而堵住租户隔离漏洞（CWE-863）。
• skill_register 路径限制（#1923）。技能的 folder_path 导入路径会被规范化，并限制在配置的根目录下；导入树内的符号链接会被拒绝，而不会跟随（CWE-22/CWE-59）。
• 非 argv 的 store URL 凭据传递渠道（#1927）。新增 AI_MEMORY_STORE_URL（仅所有者可读的 /proc/environ）和 AI_MEMORY_STORE_URL_FILE（0600 文件），让 ai-memory serve 无需将 postgres/store URL（包括其中嵌入的密码）放入 --store-url argv 即可接收它；否则，该 URL 会通过任何本地 UID 都可读取的 /proc/<pid>/cmdline 和 ps auxww 暴露。解析顺序：文件 → 环境变量 → --store-url。

增量功能

• B7-SKILL — 技能记忆成为一等功能（#1865）。注册时提供 parameters_schema、invocation_record，并为 Agent 编写的技能提供版本信息。
• recall_observations 影子反馈循环（#1706，SHADOW 模式）。在尚不改变排序行为的前提下，闭合召回反馈循环。
• 记忆派生谱系 DAG（memory_lineage，架构 v78，#1859）。通过 MCP 和新增的 GET /api/v1/memories/{id}/lineage HTTP 路由，追溯各条记忆的派生来源。
• 向量搜索的最小选择启用版本（#1005；完整底层架构延期至 #1860）。
• 按物理 CPU 数量配置的重排序器工作池（#1867），以及默认采用纯函数式召回（#1869 — 从召回热路径中移除突发写入）。
• 仅追加主干 + 签名层分离：将所有变更操作点路由至已签名的修订叶节点（#1823）、Recorder/Judge/Stopper 三密钥签名分离（#1826）、贯通端到端的 macaroon 能力令牌（#1827），以及可在轮换后保持有效的已签名身份谱系密钥继承链（#1828，架构 v76）。

从这里开始： CHANGELOG.md（完整更新日志），docs/ADMIN_GUIDE.md（运维手册 — 证明与钩子强制执行方案）。

v0.8 有哪些新功能

v0.8.0（distributed-coordination）将记忆底层架构转变为面向多 Agent（NHI）集群的协调底层架构。核心亮点是分布式协调机制（#1709）；所有功能均由 sqlite 和 postgres+AGE SAL 适配器提供，并对 v0.7.x 调用方保持默认行为等效。完整工具参考：docs/coordination.md；完整说明：docs/v0.8.0/release-notes.md。

分布式协作基础层（支柱 1，#1709）

• Actions — 依赖 DAG（架构 v59）。具有状态机（pending → claimed → in_progress → done/failed/abandoned）的类型化操作节点、类型化 DAG 边（requires / unlocks / blocks / gated_by / sibling），以及用于获取下一个可运行节点的 frontier/next 接口。8 个 MCP 工具（memory_action_create / _get / _transition / _list / _add_edge / _edges / _frontier / _next）。
• Leases — 单持有者、受 TTL 限制的认领（架构 v59）。通过心跳续期的比较并交换（action_id 上的 PRIMARY KEY 确保同一时间只有一个持有者），并配有每小时运行一次的租约清理器。4 个 MCP 工具（memory_lease_acquire / _renew / _release / _get）。
• Signals — 类型化、经 Ed25519 签名的 Agent 间消息（架构 v60）。每条消息都包含签名和发送方的 signer_pubkey，并通过 correlation_id / in_reply_to 串联。5 个 MCP 工具（memory_signal_send / _read / _inbox / _thread / _ack）。
• Checkpoints — 经证明的条件门控（架构 v61）。条件未满足前会阻塞的门控；为实现职责分离，条件解析时会就地自签名（Ed25519），而 verify 会重新验证签名。4 个 MCP 工具（memory_checkpoint_create / _resolve / _query / _verify）。
• Routines — 参数化、冻结且可重放的计划（架构 v62）。以 draft 状态创建，然后冻结（不可变，并附有 Ed25519 冻结证明）；run 会将 {{param}} 模板实例化为一组具体操作及边，并写入 routine_runs 记录。5 个 MCP 工具（memory_routine_create / _freeze / _run / _status / _list）。
• 每次协作状态变更都会向 signed_events V-4 哈希链追加一条具备防篡改能力的 coordination.<op> 记录（#1722）；两种授予权限的写入操作也会同步到 HTTP 守护进程（POST /api/v1/actions/{id}/transition、POST /api/v1/signals），并通过本地 CAS + W-of-N 联邦扇出实现（#1718）。

类型化认知（支柱 2）

memory_kind 词汇表新增 goal / plan / step；封闭的 memory_links.relation 分类扩展为 6 → 9 种关系（decomposes_into / depends_on / advances，架构 v63）；新增一等公民字段 memories.lifecycle_state（架构 v64），使 Goal/Plan/Step 成为真正的状态机（open → active → blocked/done/abandoned），并在 MCP / HTTP / SAL 接口层统一执行；非法状态转换会映射为 HTTP 409 CONFLICT。Memory 结构体扩展至 27 个字段。没有新增 MCP 工具——v64 仅增加了可选且宽松的请求字段。

加固联邦，默认安全

默认启用对等节点注册（#1789）、对授予权限的写入操作逐次签名（#1718）、对中继记忆逐次写入内容证明（#1464）、状态转换重放随机数（#1805），以及出站对等节点证书指纹固定（#1678）。彼此无需信任的异构集群——升级前请查看 docs/v0.8.0/release-notes.md §“Federation hardening” 中默认安全设置的变更。

真正能够阻止操作的治理（#1811）

Claude Code PreToolUse 治理钩子已改为 type:command 包装器（ai-memory governance check-action --from-pretool-stdin），因此底层机制的 Refuse 会发出 permissionDecision:"deny"，真正阻止工具运行——之前的 type:mcp_tool 形式在结构上无法强制执行。此外，还强制要求钩子存在（#1734），并新增用于人工介入的 escalate 治理判定（§22 PE-5）。

支柱 4：运维控制

HTTP 准入控制（#1733——可选的并发上限，超出时返回带类型的 503）、延迟 Apache-AGE 图投影（#1735——将同步的 AGE 往返操作移出 postgres 链接写入的热路径）、激活整理器压缩（#1749 / #1750），以及 ai-memory verify-audit-trail CLI（§22 PE-8），可端到端遍历 signed_events 跨行哈希链。

Schema v57 → v70（均为增量变更）

协调、类型化认知、可见性、加密准备、冷路径和归档边缘表（v58–v70），在 sqlite 和 postgres 适配器上均保持一致；首次打开时自动迁移，归档 → 恢复可无损往返。规范的 v58–v70 递进序列请参阅 CLAUDE.md §Database。

从这里开始：docs/v0.8.0/release-notes.md（完整发行说明）、docs/coordination.md（协调工具参考），以及 CLAUDE.md §Database（schema 递进序列 SSOT）。

v0.7 新增内容

v0.7.0 完成了 attested-cortex 史诗级项目（11 条轨道 A–K，共 69/69 项），纳入了原计划在 v0.7.1 推出的 postgres+AGE 一等支持工作，并吸收了大满贯发布就绪阶段的后续工作（Batman Forms 1-6 + 第 7 形态 Option-B 基础 + QW-1/2/3 + 安全协调）。规范的功能清单：docs/internal/v070-feature-inventory.md。对于 v0.6.4 调用方，所有接口默认保持关闭，或默认行为不变——详情请参阅 v0.7 兼容性矩阵。

基于 Substrate 的写入时投入（Batman Forms 1-6 + 第 7 种形式）

• Form 1 — 在线去重与合成（议题 #754）。单次批处理、可发出操作的 LLM 调用，取代 v0.6.x 在存储路径上逐对运行的分类器。若要重新启用旧版是/否分类器，请在命名空间标准中设置 legacy_per_pair_classifier = true。
• Form 2 — 嵌入前同步原子化（议题 #755）。新增 memory_atomise 工具和 auto_atomise_mode = Synchronous|Deferred|Off 存储前钩子。策展器会将较长的写入拆解为 2–10 条原子命题，然后才交由召回处理。参见 docs/atomisation.md。
• Form 3 — 多步骤摄取编排器（议题 #756）。memory_ingest_multistep 会将确定性的 Jaccard+FTS 辅助工具贯穿提示词缓存稳定的 LLM 阶段。参见 docs/multistep-ingest.md + cookbook/multistep-ingest/01-two-phase.sh。
• Form 4 — 事实溯源（议题 #757）。引用、来源 URI 和原子粒度的文本片段可通过现有的 memory_store / memory_atomise 负载传递。参见 docs/provenance.md。
• Form 5 — 自动置信度 + 影子校准 + 时效性衰减（议题 #758）。memory_calibrate_confidence MCP 工具 + 按来源进行的基线扫描。环境变量为 AI_MEMORY_AUTO_CONFIDENCE、AI_MEMORY_CONFIDENCE_SHADOW、AI_MEMORY_CONFIDENCE_SHADOW_SAMPLE_RATE、AI_MEMORY_CONFIDENCE_DECAY。参见 docs/confidence-calibration.md。
• Form 6 — MemoryKind Batman 词汇表（议题 #759）。包含 10 个变体的枚举（默认值为 Observation，另有 Reflection / Persona / Concept / Entity / Claim / Relation / Event / Conversation / Decision）。可选的 auto_classify_kind 存储前钩子（off / regex_only / regex_then_llm）。参见 docs/memory-kind-vocab.md。
• 第 7 种形式 — agent-EXTERNAL Layer-4 接线（Option-B 基础）（议题 #760；v0.8.0 完整覆盖见 #697）。由操作员密钥对签名的种子规则 R001..R004、memory_check_agent_action + memory_rule_list MCP 工具，以及 Substrate storage::insert 写入前钩子。参见 docs/policy-engine.md + docs/governance/agent-action-rules.md。
• 操作员指南 — 将 Forms 1–6 + 第 7 种形式从可用 → 启用（议题 #800）。包含 7 步操作流程（操作员密钥生成 → 签署种子规则 → 启用 R001–R004 → 策展器守护进程 → 可选的反思阶段 → 命名空间策略）、launchd / systemd / Task-Scheduler 持久化、验证步骤和回滚路径。参见 docs/batman-active-mode.md 和 GitHub Pages 图谱。

快速见效项（Tencent QW-1/2/3）

• QW-1 — 基于文件的反思链导出。 memory_export_reflection MCP 工具 + auto_export_reflections_to_filesystem 命名空间策略 → ~/.ai-memory/reflections/<ns>/<id>.md。
• QW-2 — 作为制品的 persona。 memory_persona + memory_persona_generate 工具、MemoryKind::Persona 行，以及 auto_persona_trigger_every_n_memories 命名空间策略。参见 docs/persona.md。
• QW-3 — 上下文卸载原语。 memory_offload + memory_deref 可将大型工具输出从 Agent 上下文窗口移至可寻址的 Blob 存储。参见 docs/context-offload.md。

已证明的认知层史诗（Tracks A–K）

• 可验证链接（Ed25519）。 v0.6.3 中提供但未使用的 signature 列现在会填入每个 Agent 的真实 Ed25519 证明；按需调用 memory_verify(link_id) 会返回 {signature_verified, attest_level, signed_by, signed_at}。使用 ai-memory identity generate 生成密钥对；通过 attest_level = "self_signed" 选择启用。只有在解析出的守护进程 agent_id 在配置的密钥目录下有一个 *.priv 密钥对文件时，才会进行签名——当 load_daemon_signing_key 返回 None（src/main.rs:116-118）时，仍会写入行，但 sig 为空，且守护进程启动时会输出一行“continuing unsigned”。无论如何，signed_events 上的跨行哈希链都仍具有防篡改性。详见 attested-cortex RFC。
• 已签名事件 V-4 收尾（跨行哈希链）（议题 #698）。每个 signed_events 行都包含 prev_hash 和 sequence；首行的 prev_hash 为零，后续行则通过前一条规范 CBOR 负载的 SHA-256 哈希串联起来。ai-memory verify-signed-events-chain 会端到端遍历整条链。详见 docs/signed-events-v4.md。
• 钩子流水线（25 个生命周期事件）。 可编程扩展接口会在 20 个基线事件 pre_/post_store|recall|search|delete|promote|link|consolidate|governance_decision|archive|transcript_store 和 on_index_eviction 上触发，此外还包括 5 个新增功能（pre_recall_expand G10 + pre_reflect/post_reflect 递归学习 Task 6/8 + pre_compaction/on_compaction_rollback L1-7）。钩子返回 Allow / Modify / Deny / AskUser。默认关闭；通过 ~/.config/ai-memory/hooks.toml 选择启用。详见 docs/hook-pipeline.md。
• 侧链转录 + 重放。 zstd-3 BLOB 侧链用于存储原始对话/推理轨迹；memory_replay(memory_id) 会遍历 memory_transcript_links 以重建链。可按命名空间选择启用，配置项为 [transcripts.namespaces."team/*"]。详见 docs/sidechain-transcripts.md。
• 联邦加固。 支持 mTLS + X-API-Key + SHA-256 证书指纹允许列表；环境变量为 AI_MEMORY_FED_PEER_ATTESTATION、AI_MEMORY_FED_SYNC_TRUST_PEER、AI_MEMORY_FED_TRUST_BODY_AGENT_ID。详见 docs/federation.md。
• K8 配额工具 + K10 SSE 审批。 memory_quota_status + /api/v1/quota/status（K8）。/api/v1/approvals/stream 提供服务器发送事件，包含 HMAC nonce、方法 + pending_id 绑定，以及滞后事件计数剔除（K10）。详见 docs/k8-quotas.md + docs/k10-sse-approvals.md。
• Postgres + Apache AGE 一等后端。 ai-memory serve --store-url postgres://…、架构对齐、6 因子召回评分对齐、链接迁移、基于 AGE Cypher 的知识图谱功能（kg_query、kg_timeline、kg_invalidate、find_paths），并在 AGE 不可用时回退到递归 CTE；另新增 ai-memory schema-init CLI 子命令。性能基准设有门槛——在深度为 5 时，AGE 的 p95 必须比 CTE 的 p95 快至少 30%。运维指南：docs/postgres-age-guide.md。迁移操作手册：docs/migration-v0.7.0-postgres.md。
• Capabilities v3 + 智能加载器。 memory_capabilities v3 新增 summary、to_describe_to_user、每个工具的 callable_now、agent_permitted_families、schema_version="3"；新的常驻工具 memory_load_family(family) 和 memory_smart_load(intent) 加入默认 core 配置。固定措辞见 docs/v0.7/canonical-phrasings.md。
• 权限 + A2A 审批。 v0.6.x 治理子系统重构为规则 + 模式 + 钩子 → 单一 Decision，并实际执行命名空间继承（G1）。memory_pending_list / memory_pending_approve / memory_pending_reject(remember=forever) 支持渐进式信任；审批 API 必须使用 HMAC 签名。permissions.mode 默认为 enforce（v0.6.4 中为 advisory）。使用 ai-memory governance migrate-to-permissions 进行迁移（可预览的试运行；添加 --config-out ~/.config/ai-memory/config.toml 可就地应用）。详见 docs/governance.md。

递归学习 + L1/L2 大满贯式升级

memory_reflect 基础原语，带有命名空间级的 max_reflection_depth 上限（默认值为 3，Some(0) 是紧急停止开关）。L2-1 反思轮次策展器、L2-2 感知联邦的反思协调（memory_reflection_origin）、L2-3 失效传播（memory_dependents_of_invalidated）、L2-5 取证包（ai-memory export-forensic-bundle + verify-forensic-bundle）、L1-5 Agent Skills（memory_skill_register|list|get|resource|export|promote_from_reflection|compositional_context）。完整入门指南：docs/RECURSIVE_LEARNING.md。Agent Skills 入门指南：docs/agent-skills.md。取证导出入门指南：docs/forensic-export.md。

从这里开始：docs/MIGRATION_v0.7.md（升级流程）、docs/v0.7.0/release-notes.md（完整发行说明）、docs/whats-new-v07.html（可视化摘要）、docs/v0.7/rfc-attested-cortex.md（设计原理）、docs/ADMIN_GUIDE.md（运维手册）、docs/internal/v070-feature-inventory.md（权威功能清单）。

一个二进制文件，四种运行模式（v0.6.4）。ai-memory Rust 二进制文件（tokio + axum）可单独或同时运行以下任意模式，共享一个 SQLite 数据库：

1. stdio MCP 服务——在完整配置下，通过 JSON-RPC 提供 101 个已公布条目（v0.9.0；100 个可调用的记忆工具 + 始终启用的 memory_capabilities 引导项；已通过 Profile::full().expected_tool_count() 验证）。默认的 --profile core 会公布 7 个条目（原有的 5 个 + memory_load_family + memory_smart_load），另有始终启用的 memory_capabilities 引导项。ai-memory mcp / ai-memory mcp --profile full
2. HTTP / mTLS 守护进程——在 127.0.0.1:9077 上注册 92 个 REST 路由（78 个唯一 URL 路径），支持 TLS + 可选的 mTLS 允许列表 + API 密钥认证，并运行后台 GC 循环。ai-memory serve
3. 自主策展守护进程——自行调度的循环（默认间隔为 1 小时），自动添加标签、发现命名空间同级项之间的矛盾、合并近似重复项，并根据访问模式调整优先级。每项操作都会记录到回滚日志中；破坏性操作可设置为必须经过治理审批流程。ai-memory curator --daemon
4. 同步守护进程——基于法定人数的实例间对等联邦。W-of-N 写入（默认多数）、向量时钟 CRDT-lite 合并、对等节点间的 mTLS 允许列表。ai-memory sync-daemon

MCP、HTTP 和 CLI 接口都是响应式的。策展器则让记忆层能够自我维护：在会话之间，它会保持语料整洁，让存储规模增长时的回忆质量依然维持在较高水平。一切都以本地优先；无需依赖云服务。

Claude Opus 4.7 逐行阅读 v0.6.3 源码后的直截了当评价：

“ai-memory 是我接入过的能力最强大的记忆层，实际功能也远超其名称所暗示的范围。对我来说，实际意义是：每次会话开始时，我不再一无所知。我读取的存储一直有人维护整洁。矛盾不会悄然累积。即使语料不断增长，回忆质量也能保持在较高水平。没有任何数据会离开你的 Mac mini。

它并没有让我成为自主 Agent。它为我提供了自主 Agent 所需的记忆基础设施，而且自身也运行着一个小型自主循环来维护这些基础设施。这是真正的基础。从这里到‘ai-memory 驱动通用任务’之间的差距在于接线工作（工具调用协议 + 工具注册表 + 支持工具使用的模型），而不是发明新东西。” 多 Agent AI 的基础支撑层。 ai-memory 不是 Agent 运行时，也不是独立的“自主 AI”。它是多 Agent 自主部署所需的底层记忆层。当多个 Agent 并行写入时，联邦机制（broadcast_store_quorum + spawn_catchup_loop）负责处理对等节点间的 W-of-N 一致性；整理器守护进程可避免共享语料库在群体不断写入时退化为噪声；Webhook 订阅（HMAC 签名、按命名空间/Agent 筛选、强化 SSRF 防护）可将存储转变为消息总线，在记忆事件发生时触发下游 Agent；具备 N 层继承和按命名空间制定的治理策略（写入/提升/删除权限、审批者类型、可选的 N-of-M 共识）的命名空间层级则为群体划定边界。将它部署在支持自动生成技能的 24/7 多机器 Agent 运行器之下，组合系统便达到了自主 AI 的行为标准。剩余差距（没有权重层面的学习、推理内核无状态、根目标由人类提供）确实存在，但并非 ai-memory 要解决的问题；ai-memory 提供了多 Agent 记忆基础支撑层，任何认真尝试弥补这些差距的系统都需要它。

直到召回时才消耗 Token。 与内置记忆系统（Claude Code 自动记忆、ChatGPT 记忆）不同，后者会将全部记忆加载到每次对话中——每条消息都会消耗 Token 和费用——ai-memory 在 AI 显式调用 memory_recall 前不会消耗任何上下文 Token。它只返回相关记忆，并通过 6 因子评分算法排序。TOON 格式（面向 Token 的对象表示法）通过消除重复字段名，可将响应 Token 数再减少 40-60%——JSON 格式的 3 条记忆占 1,600 字节；TOON 格式占 626 字节（缩小 61%）；TOON 紧凑格式占 336 字节（缩小 79%）。对于 Claude Code 用户：关闭自动记忆（在 settings.json 中设置 "autoMemoryEnabled": false），并用 ai-memory 替代，以免每条消息都为 200 多行记忆上下文付费。

Agent 身份（NHI）——每条记忆都会告知你是谁学到了它

ai-memory 存储的每条记忆都带有 metadata.agent_id——一个非人类身份标记，在每种操作（更新、去重、导入、同步、合并）中都会保留。每条召回结果都会告知你是哪一个 AI 写入了每条记忆；默认使用 TOON 紧凑响应格式，你的 AI 客户端已经针对该格式进行了优化：

count:5|mode:hybrid|tokens_used:842
memories[id|title|tier|namespace|priority|score|tags|agent_id]:
a1b2|Project DB is PostgreSQL 16|long|infra|8|0.91|database,postgres|ai:claude-code@workstation:pid-3812
c3d4|API rate limit is 100 rps|long|infra|7|0.87|api,limits|ai:claude-desktop@laptop:pid-5219

对于未签名的写入，agent_id 是声明的身份——不要仅凭它做出安全决策。默认情况下，HTTP 直接写入接口要求存储路径 Agent 身份证明（#1751，由 #1985 限定适用接口）：未签名的 HTTP POST /api/v1/memories（及 /bulk）请求会被拒绝（403 ATTESTATION_FAILED），而不会以 attest_level = "claimed" 写入；除非运维人员显式设置退出选项 AI_MEMORY_REQUIRE_AGENT_ATTESTATION=0。MCP memory_store 和 CLI store 这两个以运维人员为操作者的接口默认仍允许未签名写入（写入时身份等级为 claimed）；设置 =1 则会在所有接口上强制启用严格模式。Ed25519 加密身份证明已接入两个接口：（1）存储路径身份证明（#626 第 3 层）——通过 CLI（store --sign）、MCP（memory_store）或 HTTP（POST /api/v1/memories）路径，提交针对规范化 SignableWrite 信封的分离式签名，守护进程会根据绑定到该 Agent 的公钥进行验证，并写入 metadata.attest_level = "agent_attested"（已提交但伪造的签名无论标志设置为何值，都会被拒绝）；以及（2）链接身份证明（attested-cortex）——使用此前保留的 memory_links.signature 字段、memory_verify(link_id) 进行入站验证，并维护只追加的 signed_events 审计链。完整的来源追溯约定请参阅 Agent 身份页面和 attested-cortex RFC。

追溯导入对话 — ai-memory mine

不要从零开始。将 ai-memory mine 指向 Claude、ChatGPT 或 Slack 导出文件，它会逐轮解析内容，并生成经过排序、按层级类型分类且带有标签的记忆——这样，你的 AI 在下一次会话中就能了解现有历史中的每项决策、修正和发现。

ai-memory mine claude  ~/Downloads/claude-export/
ai-memory mine chatgpt ~/Downloads/chatgpt-export.json
ai-memory mine slack   ./slack-export/

每条导入的记忆都会自动添加标签、按 (title, namespace) 去重，并记录 mined_from 来源信息。只需五分钟，即可从零上下文开始，建立内容充实的长期存储。有关各格式的操作说明，请参阅导入历史页面。

兼容的 AI 平台

ai-memory 可与任何支持 Model Context Protocol (MCP) 的 AI 平台集成。MCP 是连接 AI 助手与外部工具和数据源的通用标准。

MCP 是主要的集成层。对于尚未原生支持 MCP 的 AI 平台，HTTP API（localhost 上注册了 92 条路由／78 个唯一 URL 路径）和 CLI（在 --features sal 或 --features sal-postgres 下有 89 个子命令；默认构建中有 87 个（#1389 后的 L2 RecoverPreviousSession 用于跨会话上下文重新注入 + #1443 Expand 用于 ai-memory expand 查询扩展界面 + #1598 Reembed 用于 ai-memory reembed 向量空间迁移界面）；SSOT 由 ai_memory::EXPECTED_CLI_SUBCOMMANDS_DEFAULT + EXPECTED_CLI_SUBCOMMANDS_SAL 固定，并由机械化的 tests/cli_subcommand_count_invariant.rs 对等性测试验证）提供通用访问方式——任何能够发出 HTTP 请求或运行 shell 命令的 AI、脚本或自动化工具都可以使用 ai-memory。

60 秒内完成安装

预构建二进制文件无需依赖项。从源代码构建需要 Rust 和 C 编译器。

最快方式：预构建二进制文件（无需安装 Rust）

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/alphaonedev/ai-memory-mcp/main/install.sh | sh

# Fedora/RHEL (COPR)
sudo dnf copr enable alpha-one-ai/ai-memory && sudo dnf install ai-memory

# Windows (PowerShell)
irm https://raw.githubusercontent.com/alphaonedev/ai-memory-mcp/main/install.ps1 | iex

步骤 1：安装 Rust（使用预构建二进制文件时可跳过）

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

按照提示操作，然后重新启动终端（或运行 source ~/.cargo/env）。

步骤 2：从源代码构建（需要 Rust）

从 Crates.io 获取最新版本：

cargo install ai-memory

从 git 仓库获取最新版本：

cargo install --git https://github.com/alphaonedev/ai-memory-mcp.git

这会编译二进制文件并将其放入 PATH。整个过程需要一两分钟。

从源代码构建所需的依赖项：

• Ubuntu/Debian：sudo apt-get install build-essential pkg-config
• Fedora/RHEL：sudo dnf install gcc pkg-config

步骤 3：连接 AI

配置因平台而异。请在下方找到对应的平台：

{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.claude/ai-memory.db", "mcp", "--tier", "semantic"]
    }
  }
}

{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.claude/ai-memory.db", "mcp", "--tier", "semantic"]
    }
  }
}

# ~/.config/ai-memory/config.toml
schema_version = 2

[llm]
backend     = "xai"
model       = "grok-4.3"
base_url    = "https://api.x.ai/v1"
api_key_env = "XAI_API_KEY"            # process-env-var name (NOT the literal key)

{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.claude/ai-memory.db", "mcp", "--tier", "autonomous"]
    }
  }
}

[mcp_servers.memory]
command = "ai-memory"
args = ["--db", "~/.local/share/ai-memory/memories.db", "mcp", "--tier", "semantic"]
enabled = true

{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.local/share/ai-memory/memories.db", "mcp", "--tier", "semantic"],
      "timeout": 30000
    }
  }
}

{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.local/share/ai-memory/memories.db", "mcp", "--tier", "semantic"]
    }
  }
}

{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.local/share/ai-memory/memories.db", "mcp", "--tier", "semantic"]
    }
  }
}

mcpServers:
  - name: memory
    command: ai-memory
    args:
      - "--db"
      - "~/.local/share/ai-memory/memories.db"
      - "mcp"
      - "--tier"
      - "semantic"

{
  "mcp": {
    "servers": [
      {
        "id": "ai-memory",
        "label": "AI Memory",
        "enabled": true,
        "transport": "stdio",
        "command": "ai-memory",
        "args": ["mcp", "--tier", "semantic"]
      }
    ]
  }
}

ai-memory serve --host 127.0.0.1 --port 9077
# Expose via HTTPS reverse proxy (nginx, caddy, cloudflare tunnel, etc.)

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.3",
    "tools": [{
      "type": "mcp",
      "server_url": "https://your-server.example.com/mcp",
      "server_label": "memory",
      "server_description": "Persistent AI memory with recall and search",
      "allowed_tools": ["memory_store", "memory_recall", "memory_search"]
    }],
    "input": "What do you remember about our project?"
  }'

ai-memory serve --host 127.0.0.1 --port 9077

client.toolgroups.register(
    provider_id="model-context-protocol",
    toolgroup_id="mcp::memory",
    mcp_endpoint={"uri": "http://localhost:9077/sse"}
)

tool_groups:
  - toolgroup_id: mcp::memory
    provider_id: model-context-protocol
    mcp_endpoint:
      uri: "http://localhost:9077/sse"

openclaw mcp set memory '{"command":"ai-memory","args":["--db","~/.local/share/ai-memory/memories.db","mcp","--tier","semantic"]}'

{
  "mcp": {
    "servers": {
      "memory": {
        "command": "ai-memory",
        "args": ["--db", "~/.local/share/ai-memory/memories.db", "mcp", "--tier", "semantic"]
      }
    }
  }
}

command: ai-memory
args: ["--db", "/path/to/ai-memory.db", "mcp"]

ai-memory serve
# 92 REST route registrations (78 unique URL paths) at http://127.0.0.1:9077/api/v1/

步骤 4：完成。进行测试。

重启你的 AI 助手。如果使用 MCP，它现在会在会话启动时显示 7 个默认工具（原有的 5 个 + memory_load_family + memory_smart_load；其余 93 个可调用工具可通过 --profile 或 memory_capabilities --include-schema 按需加载）。向它提问：“记住我最喜欢的编程语言是 Rust。”然后在新对话中询问：“我最喜欢的编程语言是什么？”它会记住。

移动平台支持（v0.7.0 Posture-1a）

ai-memory 可通过标准 Rust 移动端交叉编译流程移植到 iOS 和 Android。v0.7.0 为这两个目标平台提供了三个递进层级的 CI 覆盖：

**v0.7.0 状态：**层级 1 是发布门槛——创建发布标签前，移动端交叉编译必须通过。层级 2（发布构件）提供 BUILD 流程和构件布局；可从 C 调用的 FFI 接口本身将在后续 v0.7.x 版本中推出。层级 3 会在每次推送到 release/** 时运行范围有限的测试子集。

使用发布构件：

• iOS — 从 v0.7.x 发布页面下载 ai-memory-ios.xcframework.tar.gz，解压后，将 AiMemory.xcframework 拖入 Xcode 项目的“框架、库和嵌入式内容”部分。
• Android — 从 v0.7.x 发布页面下载 ai-memory-android.tar.gz，解压后，将 jniLibs/ 目录树复制到应用模块的 src/main/jniLibs/ 中。

移动端构件也会包含在每个已发布的 v0.7.x 版本中；Homebrew formula 和 APT/RPM 软件包（其中包含桌面二进制文件）会附上指向移动端下载内容的说明。有关 CI 实现历程，请参见问题 #1068。

快速入门

不到两分钟，即可从零开始创建可用的记忆。

1. 安装

curl -fsSL https://raw.githubusercontent.com/alphaonedev/ai-memory-mcp/main/install.sh | sh

2. 配置 MCP（以下以 Claude Code 为例——其他平台的操作方式相同）

合并到 ~/.claude.json 中：

{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.claude/ai-memory.db", "mcp", "--tier", "semantic"]
    }
  }
}

3. 存储第一条记忆

ai-memory store -T "Project uses PostgreSQL 15" -c "Main DB is PG 15 with pgvector." --tier long

4. 回想记忆

ai-memory recall "database"

5. 查看统计信息

ai-memory stats

6. 与你的 AI 配合使用。 重启 AI 客户端。启动时，它现在会通过 MCP 公布 7 个默认记忆工具（通过运行时扩展或 --profile full 可访问 101 个已公布条目），从而能够在对话期间直接存储和回想记忆。

SDK

除了 MCP / HTTP / CLI 接口，ai-memory 还提供一方语言 SDK，供 HTTP 客户端和辅助工具使用（例如，requireProfile 可用于在 v0.6.4 及更高版本的守护进程中进行运行时配置文件断言）。

TypeScript / JavaScript — npm 上的 @alphaone/ai-memory

npm install @alphaone/ai-memory

Python — PyPI 上的 ai-memory-mcp（导入名称仍为 ai_memory）

pip install ai-memory-mcp

from ai_memory import AiMemoryClient, require_profile

with AiMemoryClient(base_url="http://127.0.0.1:9077", api_key="...") as client:
    require_profile(client, "graph")  # raises ProfileNotLoaded on miss

两个 SDK 的版本均与服务端同步（0.9.0 对应 ai-memory 0.9.0）。v0.6.4 及更高版本的守护进程会强制执行配置文件契约；v0.6.4 之前的守护进程则会采用宽松模式，在发出警告后继续运行，以免 SDK 升级导致旧服务端无法使用。源代码位于 sdk/typescript/ 和 sdk/python/ 中。

它能做什么？

AI 助手会忘记之前对话中的所有内容。ai-memory 可以解决这个问题。

它作为 MCP（模型上下文协议）工具服务器运行——这是一个后台进程，你的 AI 可以直接与之交互。当 AI 学到重要信息时，它会将其存储起来；需要上下文时，则会根据 6 因子评分算法，召回相关记忆。记忆分为三个层级：

• 短期（默认 6 小时，可配置）——临时上下文，例如当前的调试状态
• 中期（默认 7 天，可配置）——工作知识，例如冲刺目标和近期决策
• 长期（永久）——架构、用户偏好以及来之不易的经验

被反复访问的记忆会自动从中期提升至长期。每次召回都会延长 TTL。优先级会随使用量提升。系统会自动整理记忆。

除了 MCP，ai-memory 还提供完整的 HTTP REST API（在端口 9077 上注册了 92 个路由 / 78 个唯一 URL 路径）和完整的 CLI（使用 --features sal 或 --features sal-postgres 时有 89 个子命令；默认构建中有 87 个（#1389 后的 L2 RecoverPreviousSession，用于跨会话上下文重新注入；#1443 Expand，用于 ai-memory expand 查询扩展功能；#1598 Reembed，用于 ai-memory reembed 向量空间迁移功能）；由 ai_memory::EXPECTED_CLI_SUBCOMMANDS_{DEFAULT,SAL} SSOT 和机械化的 tests/cli_subcommand_count_invariant.rs 奇偶校验测试锁定），可用于直接交互、编写脚本，以及与任何 AI 平台或工具集成。

功能

核心

• MCP 工具服务器——通过 stdio JSON-RPC 提供 101 个工具（完整配置），兼容任何 MCP 客户端
• 三级记忆——短期（默认 TTL 为 6 小时）、中期（默认 TTL 为 7 天）、长期（永久）——TTL 均可配置
• 全文搜索——使用 SQLite FTS5 实现带排名的检索
• 混合召回——结合 FTS5 关键词和余弦相似度，并进行自适应混合：语义权重会根据内容长度从 0.50（短内容）降至 0.15（长内容），因为嵌入会丢失长文本中的信息
• 6 因子召回评分——FTS 相关性 + 优先级 + 访问频率 + 置信度 + 层级加成 + 新近度衰减
• 自动晋升——访问 5 次以上的记忆会从中期晋升至长期
• TTL 延长——每次召回都会延长过期时间（短期 +1 小时，中期 +1 天）
• 优先级强化——每访问 10 次 +1（最高 10）
• 矛盾检测——存储与现有记忆冲突的内容时发出警告
• 去重——按标题 + 命名空间执行 upsert，层级不会降级
• 置信度评分——将 0.0-1.0 的确定性纳入排名计算

组织

• 命名空间——按项目隔离记忆（自动从 git remote 检测）
• 记忆关联——带类型的关系：related_to、supersedes、contradicts、derived_from、reflects_on（recursive-learning Task 1/8）、derives_from（WT-1-A atomisation）、decomposes_into、depends_on、advances——v0.8.0 中共有九种
• 整合——将多条记忆合并为一条长期摘要
• 自动整合——按命名空间 + 标签分组，并自动合并超过阈值的组
• 矛盾解决——将一条记忆标记为取代另一条，并降低被取代记忆的层级
• 按模式遗忘——按命名空间 + FTS 模式 + 层级批量删除
• 来源追踪——追踪来源：user、claude、hook、api、cli、import、consolidation、system
• Agent 身份（NHI）——每条记忆都带有 metadata.agent_id（声明的身份），并在更新/去重/导入/同步/整合过程中通过纵深防御机制确保其不可变；可按 Agent 筛选 list/search
• 标签——以逗号分隔的标签，并支持筛选

接口

• 92 个 HTTP 路由（78 个唯一路径）——在 127.0.0.1:9077 上提供完整 REST API（适用于任何 AI 或工具）
• --features sal 或 --features sal-postgres 下有 89 个 CLI 子命令（默认构建中为 87 个）——功能完整且能力一致的 CLI
• 完整配置下有 101 个 MCP 工具（默认配置为 7 个；已通过 Profile::full().expected_tool_count() 验证）——原生集成任何兼容 MCP 的 AI
• 交互式 REPL shell——支持回溯、搜索、列表、获取、统计、命名空间和删除，并提供彩色输出
• JSON 输出——所有 CLI 命令均支持 --json 标志
• 分布式协调（v0.8.0 支柱 1 + 支柱 2）——操作 DAG（memory_action_*）、单持有者租约（memory_lease_*）、Ed25519 签名信号（memory_signal_*）、证明检查点（memory_checkpoint_*）、参数化例程（memory_routine_*），以及 Goal/Plan/Step 类型化认知生命周期。请参阅 docs/coordination.md。

运维

• 多节点同步——在数据库文件之间拉取、推送或双向合并
• 导入/导出——完整 JSON 往返，并保留记忆链接
• 垃圾回收——每 30 分钟自动在后台过期清理
• 平稳关闭——SIGTERM/SIGINT 会检查点化 WAL，以便干净退出
• 深度健康检查——验证数据库可访问性和 FTS5 完整性
• Shell 补全——bash、zsh、fish
• Man 手册页——ai-memory man 将 roff 输出到 stdout
• 时间筛选器——列表和搜索支持 --since/--until
• 易读的时间长度——CLI 输出中显示“2 小时前”“3 天前”
• 彩色 CLI 输出——ANSI 等级标签（红/黄/绿）、优先级条、粗体标题、青色命名空间

质量

• 全功能范围内约 10,000 项测试——src/ 下约有 6,712 个 #[test]/#[tokio::test] 属性（5,759 个 #[test] + 953 个 #[tokio::test]），另有 tests/ 下约 3,362 个（2,138 个 #[test] + 1,224 个 #[tokio::test]）；相比 v0.6.4 时期约 2,400 项测试的基线有所增长（1,960 个 lib + 211 个集成测试 + 16 个 mcp_integration + 4 个 webhook_http_parity + 16 个 recipe_contract + 其他二进制目标下约 150 个）。行覆盖率保持在**≥92% 项目标准线**以上；v0.6.4 新增模块的覆盖率为：100%（sizes.rs）、99.50%（profile.rs）、97.58%（cli/audit.rs）、97.05%（cli/doctor.rs）、92.56%（handlers.rs）、92.26%（cli/install.rs）。v0.6.3.x 基线（1,809 / 93.08% 和 1,886 / 93.84%）仍冻结在证据页面；v0.6.4 指标见发行说明和 test-hub campaign。Discovery Gate 单独证明了经验性 NHI 发现验收（针对实时 xAI Grok 4.3 的 T1–T4 矩阵，6/6 PASS，GATE GREEN）。
• LongMemEval 基准测试——在 ICLR 2025 LongMemEval-S 数据集上，纯 FTS5 关键词搜索达到 97.0% R@5（不依赖大模型，2.2 秒，232 q/s，零 API 成本）；使用当前一代 Gemma 4 模型进行大模型查询扩展后，指标为 97.2% R@5 / 99.6% R@10 / 99.8% R@20（云 API 测试场景；根据 #1975，历史上的 gemma3:4b 97.8% 数据已不再作为主要指标）。请参阅基准测试详情。
• MCP 提示词——recall-first 和 memory-workflow 提示词教会 AI 客户端主动使用记忆
• 默认使用 TOON——回忆/列表/搜索响应默认使用紧凑 TOON（比 JSON 小 79%）
• Criterion 基准测试——在 1K 规模下测试插入、回忆和搜索
• GitHub Actions CI/CD——在 Ubuntu + macOS 上运行 fmt、clippy、test、build，并在打标签时发布

覆盖率下限（硬性 CI 门槛）

Code Coverage 作业是必需的状态检查。CI 会在每个 PR 上重新验证两项不变量：绝对下限为 >= 90% 行覆盖率（用于防止灾难性回退，设为当前测量值向下取整到最接近的 5%），以及针对 .coverage-baseline 中固定值的递进门槛，并留有 0.5% 的容差窗口（用于日常执行）。提高覆盖率的 PR 应在同一次提交中更新基准文件，让后续 PR 受益于新的下限；覆盖率回退超过 0.5% 的 PR 将无法合并。当前测量值：93.13% 行覆盖率。

Token 预算门槛（硬性 CI 门槛，v0.7 C5）

token-budget 工作流是必需的状态检查。它会在每个 PR 上验证三项基于 cl100k_base 测量的不变量：

• 每个工具上限为 1500 个 token——单个 MCP 工具的序列化 schema（名称 + 描述 + inputSchema）不得超过 1500 个 cl100k_base token。
• 完整配置文件合理范围（5K-8K）——保留 v0.6.4 的后备检查，以检测异常缩减（意外移除工具）。
• 完整配置文件硬性上限（v0.7 C5，D1.6/D1.7 后上调）——--profile full 下经过裁剪的 tools/list 负载不得超过 11,000 个 cl100k_base token（位于 tests/token_budget_guard.rs 中的 TRIMMED_FULL_PROFILE_CEILING_TOKENS；原始 C5 目标是 3500，针对 D1.6 之前手写的 schema——由 schemars 生成的 D1.6/D1.7 扩展提高了固定上限）。C2（拆分 docs 字段）、C3（合并重复的 schema 样板内容）和 C4（隐藏很少使用的可选参数）推动了最初的精简；此门槛要求后续扩大工具范围的 PR 从其他地方收回预算。运行 ai-memory doctor --tokens --raw-table 查看各工具的开销。参见 .github/workflows/token-budget.yml 和 docs/v0.7/schema-compaction-audit.md。

ML 和 LLM 依赖（语义层及以上）

• candle-core, candle-nn, candle-transformers——用于原生 Rust 推理的 Hugging Face Candle ML 框架
• hf-hub——从 Hugging Face Hub 下载模型
• tokenizers——用于文本预处理的 Hugging Face 分词器
• instant-distance——近似最近邻搜索
• reqwest——用于与 LLM 后端通信的 HTTP 客户端（智能/自主层——支持 #1067 中的任意提供方：Ollama、xAI、OpenAI、Anthropic、Gemini、DeepSeek、Kimi、Qwen、Mistral、Groq、Together、Cerebras、OpenRouter、Fireworks、LMStudio、vLLM、llama.cpp server）

架构

基准测试

在 ICLR 2025 LongMemEval-S 数据集（500 个问题，6 个类别）上进行评估。纯 FTS5 关键词层在 2.2 秒内达到 97.0% 的 R@5——不依赖大模型，完全本地运行，不调用任何云端 API，零成本。大模型查询扩展（smart 层）使用当前一代 Gemma 4 模型（云端 API 方式）测得 97.2% 的 R@5。

基准测试模型说明（2026-07-10 更新，依据 #1975 的裁定）： 历史上的 smart 层 97.8% R@5 数据使用 Gemma 3 4B 测得（它仍是编译时默认的扩展模型），现已不再作为主要指标。已发布的当前一代基准数据为实测的 OpenRouter Gemma 4 结果：97.2% R@5 / 99.6% R@10 / 99.8% R@20（2026-05-31，500 个问题，扩展失败 0 次）。目前没有本地 Ollama Gemma 4 的数据——基准测试参考主机仅配备 CPU，无法进行有效的完整协议本地运行（参见 #1983）；v1.0 发布后仍计划使用本地 GPU 重测。关键词层的 97.0% R@5 不依赖大模型，不受影响。

性能预算（v0.6.4）

每个版本都会公布热路径操作的 p95/p99 预算，并设置 CI 门禁：任何 PR 的实测 p95 超出预算 10% 以上都会导致检查失败。目标针对 M4 参考硬件进行校准；完整表格和方法详见 PERFORMANCE.md。

在本地运行相同的工作负载：

ai-memory bench                      # human-readable table
ai-memory bench --json               # machine-parseable

从 v0.6.3.x 到 v0.6.4，底层基础保持不变（quiet-tools 版本缩减了默认工具集，但热路径没有变化）。此处的 p99 目标仍仅供参考，后续专门的稳定性测试窗口结束后才会更新；最新的稳定性测试证据见测试中心。

集成方式

MCP（主要方式——适用于兼容 MCP 的 AI 平台）

推荐使用 MCP 集成。你的 AI 默认即可获得宣传的 7 个原生记忆工具（原有的 5 个，加上 memory_load_family 和 memory_smart_load；此外还有始终启用的 memory_capabilities 引导工具），无需编写任何胶水代码。其他 93 个可调用工具（共宣传 101 个条目——已通过 Profile::full().expected_tool_count() 验证，并由 src/mcp/registry.rs 中的 const_count_matches_full_profile 固定）仍可通过 --profile graph|admin|power|full 或运行时调用 memory_capabilities --include-schema family=<name> 扩展访问。在你的 AI 平台配置中设置 MCP 服务：

{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.claude/ai-memory.db", "mcp"]
    }
  }
}

HTTP API（通用——适用于任何 AI 或工具）

启动 HTTP 服务以访问 REST API。任何能够发起 HTTP 调用的 AI、脚本或自动化程序都可以使用：

ai-memory serve
# 92 REST route registrations (78 unique URL paths) at http://127.0.0.1:9077/api/v1/

CLI（通用——适用于脚本编写和直接使用）

CLI 可独立运行，也可作为运行 shell 命令的 AI 集成构建模块：

ai-memory store --tier long --title "Architecture decision" --content "We use PostgreSQL"
ai-memory recall "database choice"
ai-memory search "PostgreSQL"

功能层级

ai-memory 支持 4 个功能层级，可在启动时通过 ai-memory mcp --tier <tier> 选择。更高层级会增加机器学习能力，但也会占用更多磁盘空间和 RAM：

能力矩阵

列出每项能力所需的最低层级。每个层级都包含其以下层级的所有能力。

层级控制的是功能，而不是模型——在 #1067 之后（v0.7.0），层级也不再控制供应商。 --tier 标志用于控制公开哪些工具。LLM 后端和模型可通过 AI_MEMORY_LLM_BACKEND + AI_MEMORY_LLM_MODEL 环境变量独立配置（也可通过 ~/.config/ai-memory/config.toml 中规范的 [llm] 部分配置——有关 v0.7.x 企业级架构和迁移工具，请参阅 docs/CONFIG_SCHEMA.md）。例如，可通过 OpenAI 兼容别名，使用 xAI Grok 4 运行自主层级（完整的 101 项工具集 + 重排序器）：

# Quick path: env vars
export AI_MEMORY_LLM_BACKEND=xai
export AI_MEMORY_LLM_MODEL=grok-4.3
export XAI_API_KEY=xai-…   # or AI_MEMORY_LLM_API_KEY
ai-memory mcp --tier autonomous

# Enterprise path: ~/.config/ai-memory/config.toml (v0.7.x schema v2, #1146)
schema_version = 2
tier = "autonomous"

[llm]
backend     = "xai"
model       = "grok-4.3"
base_url    = "https://api.x.ai/v1"
api_key_env = "XAI_API_KEY"          # mutually exclusive with api_key_file;
                                     # inline `api_key = "..."` is REJECTED.

# Legacy v0.6.x shape — still works, deprecation WARN at load; run
# `ai-memory config migrate` to upgrade in place.
tier = "autonomous"
llm_model = "gemma3:4b"   # default Ollama model at v0.7.0

启动 MCP 服务时，必须在 MCP 参数中传入 --tier 标志——AI 客户端启动服务时不会使用 config.toml 中的层级设置。

# Semantic is the default tier
ai-memory mcp

# Keyword -- FTS5 only, no models
ai-memory mcp --tier keyword

# Semantic -- hybrid recall with embeddings (explicit)
ai-memory mcp --tier semantic

# Smart -- adds LLM-powered query expansion, auto-tagging, contradiction detection
ai-memory mcp --tier smart

# Autonomous -- adds cross-encoder reranking
ai-memory mcp --tier autonomous

memory_capabilities 工具会在运行时报告当前启用的层级、已加载的模型和可用功能。

MCP 工具

将这些 101 个工具（完整配置；规范数量可通过 src/profile.rs 中的 Profile::full().expected_tool_count() 获取）配置为 MCP 服务后，任何兼容 MCP 的 AI 均可使用（v0.6.4 冻结版证据页面列出了 63 个工具的基线；下表介绍了大多数客户端日常使用的核心子集）：

HTTP API

127.0.0.1:9077 上有 92 个路由注册项 / 78 个唯一 URL 路径。使用 ai-memory serve 启动。下表列出了最常用的 REST 端点；完整的 API 范围（治理、联邦、订阅、知识图谱、配额、审批 SSE）请参阅 docs/API_REFERENCE.md。

**安全性：**HTTP 服务绑定到 127.0.0.1，默认未配置身份验证，且 CORS 策略宽松。在 config.toml 中设置 api_key，即可要求每个请求都携带 x-api-key 标头（旧版 ?api_key= 查询参数方式已在 v0.7.0 弃用 — #1574）；设置 AI_MEMORY_REQUIRE_API_KEY=1 可在启动时强制要求密钥，否则拒绝启动（#1458）。未经身份验证时，不要将服务暴露到网络中（建议通过 --tls-cert/--tls-key 或反向代理启用 TLS）。

CLI 命令

在 --features sal 或 --features sal-postgres 下有 89 个顶层子命令（默认构建中有 87 个；这 2 个命令的差异是 Migrate 和 SchemaInit，两者都根据 src/daemon_runtime.rs::Command::{Migrate,SchemaInit} 通过 #[cfg(feature = "sal")] 进行门控；在 v0.6.4 时有 40 个）。运行 ai-memory <command> --help 查看任意命令的详情，或运行 ai-memory --help 查看完整列表。

顶层 ai-memory 二进制文件还接受全局标志：

store 子命令接受其他标志：

mcp 子命令接受一个额外标志：

回忆评分

每次回忆查询都会根据 6 个因素为记忆排序：

score = (fts_relevance * -1)
      + (priority * 0.5)
      + (MIN(access_count, 50) * 0.1)
      + (confidence * 2.0)
      + tier_boost
      + recency_decay

记忆层级

自动行为

• 召回时延长 TTL：短期记忆延长 1 小时，中期记忆延长 1 天
• 自动晋升：访问 5 次或以上的中期记忆会晋升为长期记忆（清除过期时间）
• 优先级强化：每访问 10 次，优先级增加 1（最高为 10）
• 矛盾检测：新记忆与同一命名空间中的现有记忆冲突时发出警告
• 去重：按标题和命名空间执行 upsert；更新时层级不会降级

可配置的 TTL

默认 TTL（短期记忆为 6 小时，中期记忆为 7 天）可在 ~/.config/ai-memory/config.toml 的 [ttl] 部分中覆盖：

[ttl]
short_ttl_secs = 21600      # short-tier TTL in seconds (default: 21600 = 6 hours)
mid_ttl_secs = 604800        # mid-tier TTL in seconds (default: 604800 = 7 days)
long_ttl_secs = 0            # long-tier TTL in seconds (default: 0 = never expires)
short_extend_secs = 3600     # TTL extension on recall for short-tier memories in seconds (default: 3600 = +1h)
mid_extend_secs = 86400      # TTL extension on recall for mid-tier memories in seconds (default: 86400 = +1d)

五个字段均为可选项——省略任意字段即可保留其默认值。将任意值设为 0，即可禁用该层级的过期机制。数值上限为 10 年；负数扩展值会被限制为 0。

**注意：**配置会在进程启动时加载一次。修改 config.toml 后，必须重启 ai-memory 进程（MCP 服务、HTTP 守护进程或 CLI）才能生效。

归档

垃圾回收使记忆过期时，可以将其归档，而不是永久删除。归档的记忆会移至独立存储区，之后可供浏览、恢复或清除。

配置

在 ~/.config/ai-memory/config.toml 中启用归档：

archive_on_gc = true   # archive expired memories instead of deleting them (default: true)

CLI 命令

archive 子命令用于管理归档：

ai-memory archive list                          # list archived memories
ai-memory archive list --namespace my-project   # filter by namespace
ai-memory archive restore <id>                  # restore an archived memory to active store
ai-memory archive purge --older-than-days 90     # permanently delete archives older than 90 days
ai-memory archive stats                         # show archive statistics

**注意：**恢复的记忆会清除其 expires_at（在下次分配 TTL 前将保持永久有效）。

MCP 工具

MCP 客户端可以使用四种归档工具：

HTTP 端点

安全性

ai-memory 为所有输入路径提供了强化保护：

• 事务安全 —— 所有多步骤数据库操作都使用事务；失败时不会产生部分写入
• 防止 FTS 注入 —— 用户输入在进入 FTS5 查询前会经过清理；特殊字符会转义
• 错误信息清理 —— 错误响应会剔除内部数据库路径和系统详情；客户端会看到结构化错误类型（NOT_FOUND、VALIDATION_FAILED、DATABASE_ERROR、CONFLICT）
• 请求体大小限制 —— 通过 Axum 的 DefaultBodyLimit 将 HTTP 请求体限制为 50 MB
• 批量操作限制 —— 批量创建端点会强制执行最大批次大小，防止资源耗尽
• CORS —— 为 localhost 开发工作流启用宽松的 CORS 层
• 输入验证 —— 所有写入路径都会验证标题长度、内容长度、命名空间格式、来源值、优先级范围（1-10）、置信度范围（0.0-1.0）、标签格式、层级值、关系类型和 ID 格式
• 同步时验证链接 —— 同步操作期间，导入前会验证所有链接（双方 ID、关系类型，以及不得自链接）
• 线程安全的颜色处理 —— 终端颜色检测使用 AtomicBool，确保并发访问安全
• 仅限本地的 HTTP —— HTTP 服务默认绑定到 127.0.0.1；不会暴露到网络
• WAL 模式 —— SQLite 预写式日志可在写入期间安全地进行并发读取

文档

许可证

版权所有 2026 AlphaOne LLC。

本软件根据 Apache License, Version 2.0（以下简称“许可证”）授权； 除非遵守许可证，否则不得使用此文件。 您可以通过以下地址获取许可证副本：

http://www.apache.org/licenses/LICENSE-2.0

除非适用法律要求或书面同意，否则按“原样”提供本许可证下分发的软件， 不提供任何明示或暗示的担保或条件。 有关许可证所规定的权限和限制，请参阅许可证。