ai-memory

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 直接写入默认要求代理证明（#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 会在每个接口上强制严格模式。（v0.9.0 GA 版本将此作为 require-everywhere 发布，这在 MCP 主机上无法满足——在当前版本中已修正为按接口限定范围。）与此同时，强制钩子存在执行门现在在 MCP 写入路径（#1885）和 HTTP 写入路径（#1924）上都会触发，关闭了一个静默绕过漏洞，即配置的强制钩子可能在一个接口上被跳过，而在另一个接口上不会。加固过程还关闭了 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）。附加功能工作：代理编写的技能记忆，带有 parameters_schema + invocation_record（B7-SKILL，#1865），recall_observations 影子反馈循环（#1706），一个记忆派生谱系 DAG（memory_lineage，#1859），以及一个可选的向量搜索最小切片（#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 关系，一个 28 字段的 Memory。在两个生产后端上运行，具有相同的 API——嵌入式 SQLite 和 PostgreSQL + Apache AGE——跨桌面、服务器和设备端（iOS + Android）。除了证明和钩子执行翻转之外，所有内容都是对 v0.8.1 的附加；这些是默认安全性的破坏性更改——升级前请审查它们。完整更新日志： CHANGELOG.md §"[0.9.0] — 2026-07-08"。

v0.8.0（distributed-coordination）— 之前的版本。 这是记忆基底成为协调基底的版本。它添加了来自 #1709 的分布式协调机制：一个带有真正状态机（memory_action_*）的类型化操作 DAG、TTL 限制的单持有者租约（memory_lease_*）、Ed25519 签名的信号（memory_signal_*）、Ed25519 证明的检查点（memory_checkpoint_*），以及冻结、可重放的例程（memory_routine_*）——这样异构的代理舰队就可以轮流工作、交接任务，并证明谁说了什么，而无需相互信任。它在此基础上分层了类型化认知（Goal/Plan/Step 记忆种类、一个 lifecycle_state 机器，以及 decomposes_into / depends_on / advances 链接关系），默认安全地加固了联邦（默认开启对等注册 #1789、每次转换签名 #1718、每次写入内容证明 #1464、转换重放随机数 #1805、出站对等证书固定 #1678），并提供了真正起作用的治理——Claude Code PreToolUse 钩子被重写为 type:command 包装器，以便基底 Refuse 真正拒绝该工具（#1811）。在 v0.8.0 版本中，接口为：模式 v70，--profile full 处有 100 个 MCP 工具（99 个可调用 + 始终开启的 memory_capabilities 引导程序）/ --profile core 处有 7 个，91 个 HTTP 路由注册（78 个唯一 URL 路径），83/85 个 CLI 子命令，9 种类型化的 MemoryLink 关系，一个 27 字段的 Memory。在两个生产后端上运行，具有相同的 API——嵌入式 SQLite 和 PostgreSQL + Apache AGE——跨桌面、服务器和设备端（iOS + Android）。所有内容都是对 v0.7.0 的附加；升级前请审查默认安全性的翻转。完整发布说明： docs/v0.8.0/release-notes.md。 v0.7.0 (attested-cortex) — 先前版本。 将 cortex-fluent 可读性工作与完整的 v0.7 信任 + A2A 范围（来自 ROADMAP §7.3）整合在一起，外加（根据操作员指令 2026-05-09）原本的 v0.7.1 postgres+AGE 一等公民工作，外加大满贯后的发布就绪浪潮（Batman Forms 1-6 + 第 7 形态 Option-B 基础 + QW-1/2/3 + 对账安全扫描）。底层变得更具表达力（capabilities v3、命名加载器工具、压缩模式、Batman MemoryKind 词汇表、persona/atomisation/multistep-ingest 原语）且密码学上可信（Ed25519 证明、侧链记录、可编程的 25 事件钩子管道、强制命名空间继承、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() 阶梯臂（文件名计数器滞后于逻辑模式版本，因为两个阶梯都通过进程内臂应用 post-v34 增量 — 有关 v35-v57 叙述，请参阅 docs/MIGRATION_v0.7.md §schema-ladder；v48 #933 添加了联邦推送 DLQ 表；v49 #1025 向 archived_memories 添加了 14 个可空列，以便存档 → 恢复对完整的 v0.7.0 Memory 形状是无损的；v50 #1156 将 agent_quotas 主键从 (agent_id) 扩展到 (agent_id, namespace)，以便即使单个代理跨多个命名空间操作，每个命名空间的 K8 配额分配也能保持 — pre-v50 行回填到 _global 哨兵命名空间；v51 #1255 (PR #1296) 添加了 federation_nonce_cache 表，以便对等重放预防随机数在守护进程重启后持久化；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 已通过索引反向扫描服务于范围扫描；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 调用者不会看到行为变化，但 pre-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%。要 1:1 保留 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 直接写入界面上默认要求代理证明（#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）。强制钩子存在执行门（最初仅限 MCP，#1734）现在也在 HTTP 写入路径上被咨询，关闭了一个静默绕过漏洞（CWE-288），即完全跳过 MCP 的写入从未看到配置的强制钩子。
• bulk_create 证明门控（#1919）。批量写入现在强制执行与单个 memory_store 调用相同的每行代理证明要求 — 批次中的每一行都必须携带有效的证明，而不仅仅是整个请求。
• 联邦批准者门（#1920）。入站联邦 PENDING 批准仅在其归属于对等方的注册批准者时才被接受 — 已注册但不受信任的对等方不能再为任意请求者伪造批准。
• team/unit/org 范围加固（#1921）。可见性范围解析现在为 team/unit/org 范围正确执行命名空间祖先层次结构，关闭了一个租户隔离漏洞（CWE-863）。
• skill_register 路径限制（#1923）。技能的 folder_path 导入被规范化并限制在配置的根目录下，导入树内的符号链接被拒绝而不是跟随（CWE-22/CWE-59）。
• 非 argv 存储 URL 凭据通道（#1927）。新的 AI_MEMORY_STORE_URL（仅所有者 /proc/environ）和 AI_MEMORY_STORE_URL_FILE（一个 0600 文件）允许 ai-memory serve 接收 postgres/store URL — 包括任何嵌入的密码 — 而无需将其放在 --store-url argv 上，在那里它会通过全局可读的 /proc/<pid>/cmdline 和 ps auxww 暴露给任何本地 UID。解析顺序：文件 → 环境变量 → --store-url。

附加功能

• B7-SKILL — 技能记忆一等公民（#1865）。注册时的 parameters_schema、一个 invocation_record，以及用于代理创作技能的版本界面。
• recall_observations 影子反馈循环（#1706，SHADOW 模式）。关闭召回反馈循环，但尚未改变排名行为。
• 记忆派生谱系 DAG（memory_lineage，模式 v78，#1859）。遍历哪些记忆派生自哪些记忆，通过 MCP 和新的 GET /api/v1/memories/{id}/lineage HTTP 路由。
• 向量搜索最小可选切片（#1005；完整底层推迟到 #1860）。
• 重排序器工作池大小调整为物理 CPU 数量（#1867）和默认情况下召回是 PURE（#1869 — 从召回热路径中移除写入突发）。
• 仅追加脊柱 + 签名层分离：每个变更点路由到签名的修订叶子（#1823），三密钥 Recorder/Judge/Stopper 签名分离（#1826），端到端连接的 macaroon 能力令牌（#1827），以及用于轮换生存的签名身份谱系密钥继承链（#1828，模式 v76）。

从哪里开始： CHANGELOG.md（完整变更日志），docs/ADMIN_GUIDE.md（操作员手册 — 证明 + 钩子执行态势）。

v0.8 中的新功能

v0.8.0 (distributed-coordination) 将记忆底层转变为用于多代理（NHI）舰队的协调底层。头条是分布式协调机制（#1709）；所有内容都在 sqlite 和 postgres+AGE SAL 适配器上提供，并对 v0.7.x 调用者保持默认等效。完整工具参考：docs/coordination.md；完整说明：docs/v0.8.0/release-notes.md。

分布式协调底层（Pillar-1，#1709）

• Actions — 依赖 DAG（模式 v59）。带状态机的类型化动作节点（pending → claimed → in_progress → done/failed/abandoned），类型化 DAG 边（requires / unlocks / blocks / gated_by / sibling），以及拉取下一个可运行节点的前沿/后续表面。8 个 MCP 工具（memory_action_create / _get / _transition / _list / _add_edge / _edges / _frontier / _next）。
• Leases — 单持有者、TTL 限定的声明（模式 v59）。心跳续约的比较并交换声明（PRIMARY KEY 在 action_id 上 = 一次一个持有者）外加每小时租约清理器。4 个 MCP 工具（memory_lease_acquire / _renew / _release / _get）。
• Signals — 类型化、Ed25519 签名的代理间消息（模式 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 §"联邦加固"中的安全默认翻转。

真正起作用的治理（#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），该 CLI 端到端地遍历 signed_events 跨行哈希链。

模式 v57 → v70（全部为增量式）

协调 + 类型化认知 + 可见性 + 加密准备 + 冷路径 + 归档边表（v58–v70），在 sqlite 和 postgres 适配器上均有镜像；首次打开时自动迁移，归档 → 恢复往返无损失。有关规范的 v58–v70 阶梯，请参阅 CLAUDE.md §数据库。

从哪里开始： docs/v0.8.0/release-notes.md（完整发布说明），docs/coordination.md（协调工具参考），以及 CLAUDE.md §数据库（模式阶梯 SSOT）。

v0.7 中的新功能

v0.7.0 关闭了 attested-cortex 史诗（11 个轨道 A–K 中的 69/69），融入了原本为 v0.7.1 的 postgres+AGE 一流工作，并吸收了后大满贯发布就绪浪潮（Batman Forms 1-6 + 7th-form Option-B 基础 + QW-1/2/3 + 安全协调）。规范功能清单：docs/internal/v070-feature-inventory.md。对于 v0.6.4 调用者，每个表面都保持默认关闭或默认等效 — 有关细分，请参阅 v0.7 兼容性矩阵。

底层原生的写入时投资（Batman Forms 1-6 + 7th-form）

• 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 通过提示缓存稳定的 LLM 阶段线程化确定性的 Jaccard+FTS 助手。请参阅 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 预存储钩子（关闭 / 仅正则表达式 / 正则表达式后 LLM）。请参阅 docs/memory-kind-vocab.md。
• 7th-form — 代理外部 Layer-4 连接（Option-B 基础）（问题 #760；v0.8.0 完整覆盖在 #697）。操作员密钥对签名的种子规则 R001..R004、memory_check_agent_action + memory_rule_list MCP 工具，底层 storage::insert 预写入钩子。请参阅 docs/policy-engine.md + docs/governance/agent-action-rules.md。
• 操作员指南 — 将 Forms 1–6 + 7th 从可用变为活跃（问题 #800）。7 步配方（操作员密钥生成 → 签名种子 → 启用 R001–R004 → 策展人守护进程 → 可选反射传递 → 命名空间策略），launchd / systemd / 任务计划程序持久化，验证块，回滚路径。请参阅 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 — 作为工件的人格。 memory_persona + memory_persona_generate 工具，MemoryKind::Persona 行，auto_persona_trigger_every_n_memories 命名空间策略。请参阅 docs/persona.md。
• QW-3 — 上下文卸载原语。 memory_offload + memory_deref 将大型工具输出从代理上下文窗口移动到可寻址的 blob 存储中。请参阅 docs/context-offload.md。

已证实的皮层史诗（轨道 A–K）

• 认证链接（Ed25519）。 v0.6.3 中提供的空 signature 列现已填充真实的每代理 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 为空，并且守护进程在启动时会发出“继续未签名”行。无论哪种方式，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 递归学习任务 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 因子召回评分对等、链接迁移、KG 功能（kg_query、kg_timeline、kg_invalidate、find_paths）在 AGE Cypher 上，当 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。
• 能力 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 代理技能（memory_skill_register|list|get|resource|export|promote_from_reflection|compositional_context）。完整入门：docs/RECURSIVE_LEARNING.md。代理技能入门：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 以完整配置文件（v0.9.0；100 个可调用内存工具 + 始终开启的 memory_capabilities 引导程序；已针对 Profile::full().expected_tool_count() 验证）通告 101 个条目。默认 --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。

它并没有让我成为一个自主代理。它给了我一个自主代理所需的那种内存基础设施——并且自身运行一个小型自主循环来维护它。这是一个真正的基础。从这里到‘ai-memory 驱动通用任务’的差距是管道（工具调用协议 + 工具注册表 + 支持工具使用的模型），而不是发明。”

多代理 AI 的基础。 ai-memory 本身不是代理运行时，也不是“自主 AI”。它是多代理自主部署在其下所需的内存层。联邦（broadcast_store_quorum + spawn_catchup_loop）处理当许多代理并行写入时跨对等体的 W-of-N 一致性；策展守护进程防止共享语料库在群体写入时退化为噪声；webhook 订阅（HMAC 签名、命名空间/代理过滤、SSRF 加固）将存储库转变为消息总线，在内存事件上触发下游代理；具有 N 级继承和每命名空间治理策略（写入/提升/删除权限、审批者类型、可选 N-of-M 共识）的命名空间层次结构约束群体。将其堆叠在具有自动生成技能的 24/7 多机代理运行器下，组合系统就达到了自主 AI 的行为标准。剩余的差距（无权重级学习、无状态推理内核、人类设定的根目标）是真实的，并且不是 ai-memory 要解决的问题；ai-memory 提供了任何认真尝试缩小这些差距都将需要的多代理内存基础。

召回前零令牌成本。 与将整个内存加载到每个对话中的内置内存系统（Claude Code 自动内存、ChatGPT 内存）不同——每条消息都消耗令牌和金钱——ai-memory 在 AI 显式调用 memory_recall 之前使用零上下文令牌。只有相关的记忆会返回，按 6 因子评分算法排序。TOON 格式（面向令牌的对象表示法）通过消除重复的字段名称，将响应令牌再减少 40-60%——JSON 中的 3 条记忆 = 1,600 字节；TOON 中 = 626 字节（小 61%）；TOON 紧凑格式中 = 336 字节（小 79%）。对于 Claude Code 用户：禁用自动内存（settings.json 中的 "autoMemoryEnabled": false）并用 ai-memory 替换它，以停止为每条消息上的 200+ 行内存上下文付费。

代理身份（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 直接写入表面需要存储路径代理认证（#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 信封的分离签名，守护进程会根据代理绑定的公钥进行验证，并加盖 metadata.attest_level = "agent_attested"（提供但伪造的签名无论标志如何都会被拒绝）；以及（2）链接认证（attested-cortex）——先前保留的 memory_links.signature 字段，带有用于入站验证的 memory_verify(link_id) 和仅追加的 signed_events 审计链。有关完整的来源合同，请参阅代理身份页面和 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 与任何支持**模型上下文协议（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

第一步：安装 Rust（如果使用预编译二进制文件，请跳过）

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

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

第二步：从源码安装（需要 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

第三步：连接你的 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；其余 100 个可调用工具中的 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 层（发布产物）交付构建流水线 + 产物布局；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 公式 + 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 个默认记忆工具（101 个通告条目可通过运行时扩展或 --profile full 访问）——它可以在对话中原生地存储和回忆记忆。

SDK

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

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 向量空间迁移接口）；SSOT 由 ai_memory::EXPECTED_CLI_SUBCOMMANDS_{DEFAULT,SAL} + 机械的 tests/cli_subcommand_count_invariant.rs 奇偶校验测试固定），用于直接交互、脚本编写以及与任何 AI 平台或工具的集成。

功能

核心

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

组织

• 命名空间 — 按项目隔离记忆（从 git 远程自动检测）
• 记忆链接 — 类型化关系：related_to、supersedes、contradicts、derived_from、reflects_on（递归学习任务 1/8）、derives_from（WT-1-A 原子化）、decomposes_into、depends_on、advances — v0.8.0 共九种变体
• 整合 — 将多个记忆合并为一个长期摘要
• 自动整合 — 按命名空间+标签分组，自动合并超过阈值的组
• 矛盾解决 — 将一个记忆标记为取代另一个，降级被取代者
• 按模式遗忘 — 按命名空间 + FTS 模式 + 层级批量删除
• 来源追踪 — 追踪来源：user、claude、hook、api、cli、import、consolidation、system
• 代理身份（NHI） — 每个记忆都携带 metadata.agent_id（声明的身份），在更新/去重/导入/同步/整合过程中具有纵深防御的不可变性；按代理过滤 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 — 带彩色输出的 recall、search、list、get、stats、namespaces、delete
• JSON 输出 — 所有 CLI 命令上的 --json 标志
• 分布式协调（v0.8.0 Pillar-1 + Pillar-2） — 操作 DAG（memory_action_*）、单持有者租约（memory_lease_*）、Ed25519 签名信号（memory_signal_*）、认证检查点（memory_checkpoint_*）、参数化例程（memory_routine_*）以及目标/计划/步骤类型化认知生命周期。请参阅 docs/coordination.md。

运维

• 多节点同步 — 数据库文件之间的拉取、推送或双向合并
• 导入/导出 — 保留记忆链接的完整 JSON 往返
• 垃圾回收 — 每 30 分钟自动后台过期
• 优雅关闭 — SIGTERM/SIGINT 检查点 WAL 以实现干净退出
• 深度健康检查 — 验证数据库可访问性和 FTS5 完整性
• Shell 补全 — bash、zsh、fish
• 手册页 — ai-memory man 生成 roff 到标准输出
• 时间过滤器 — 列表和搜索上的 --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 个 integration + 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 活动 中。经验性 NHI 发现接受度由 Discovery Gate 单独证明（T1–T4 矩阵对比实时 xAI Grok 4.3，6/6 通过，GATE GREEN）。
• LongMemEval 基准测试 — 在 ICLR 2025 LongMemEval-S 数据集上，纯 FTS5 关键词达到 97.0% R@5（独立于 LLM，2.2 秒，232 q/s，零 API 成本）；使用当前一代 Gemma 4 模型的 LLM 查询扩展测得 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 默认 — recall/list/search 响应默认使用 TOON 紧凑格式（比 JSON 小 79%）
• Criterion 基准测试 — 1K 规模下的插入、召回、搜索
• GitHub Actions CI/CD — 在 Ubuntu + macOS 上进行 fmt、clippy、测试、构建，在标签上发布

覆盖率底线（硬性 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 工具的序列化模式（名称 + 描述 + 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 目标是针对 D1.6 之前的手工编码模式设定的 3500——由 schemars 派生的 D1.6/D1.7 扩展提高了固定上限）。C2（拆分文档字段）、C3（折叠重复的模式样板）和 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 服务器）

架构

基准测试

在 ICLR 2025 LongMemEval-S 数据集（500 个问题，6 个类别）上评估。纯 FTS5 关键词层在 2.2 秒内实现了 97.0% 的 R@5——独立于 LLM，完全本地化，零云 API 调用，零成本。LLM 查询扩展（智能层）使用当前一代 Gemma 4 模型（云 API 环境）测量为 97.2% 的 R@5。

基准模型说明（2026-07-10 更新，#1975 裁定）： 历史上 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）；本地 GPU 重新运行将在 v1.0 之后保持开放。关键词层 97.0% 的 R@5 独立于 LLM，不受影响。

性能预算 (v0.6.4)

每个版本都附带针对热路径操作的已发布的 p95/p99 预算，以及一个 CI 门槛，如果任何 PR 的测量 p95 超过预算 10% 以上，则该 PR 将失败。目标针对 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 为代价增加了 ML 功能：

功能矩阵

每个功能都映射到其最低层级。每个层级都包含其下所有层级的功能。

语义层（默认）捆绑了 Candle ML 框架，并在首次运行时下载 all-MiniLM-L6-v2 模型（约 90 MB）。智能和自主层需要一个 LLM 后端——遵循 #1067 (v0.7.0)，这可以是本地的（Ollama、LMStudio、vLLM、llama.cpp 服务器）或任何兼容 OpenAI 的远程端点（xAI、OpenAI、通过 OpenAI 填充程序的 Anthropic、Google Gemini、DeepSeek、Kimi、Qwen、Mistral、Groq、Together、Cerebras、OpenRouter、Fireworks）。通过 AI_MEMORY_LLM_BACKEND 环境变量进行选择；每个供应商的 API 密钥通过 XAI_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY / GEMINI_API_KEY / DEEPSEEK_API_KEY / MOONSHOT_API_KEY / DASHSCOPE_API_KEY / 等，或规范的 AI_MEMORY_LLM_API_KEY 提供。

层级控制功能，而非模型——并且遵循 #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

--tier 标志必须在 MCP 参数中传递——当服务器由 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 端点；完整接口（治理、联邦、订阅、知识图谱、配额、审批 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 -- 为本地开发工作流启用了宽松的 CORS 层
• 输入验证 -- 每个写入路径都会验证标题长度、内容长度、命名空间格式、来源值、优先级范围（1-10）、置信度范围（0.0-1.0）、标签格式、层级值、关系类型和 ID 格式
• 同步中的链接验证 -- 在同步操作期间导入之前，所有链接都会被验证（两个 ID、关系类型、无自链接）
• 线程安全的颜色输出 -- 终端颜色检测使用 AtomicBool 以确保安全的并发访问
• 仅限本地的 HTTP -- HTTP 服务器默认绑定到 127.0.0.1；不对外暴露于网络
• WAL 模式 -- SQLite 预写日志，用于在写入期间安全地进行并发读取

文档

许可证

版权所有 2026 AlphaOne LLC。

根据 Apache 许可证，版本 2.0（“许可证”）授权； 除非遵守许可证，否则您不得使用此文件。 您可以在以下网址获取许可证副本

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

除非适用法律要求或书面同意，否则根据许可证分发的软件 均按“原样”分发， 不附带任何明示或暗示的担保或条件。 有关许可证下特定语言的权限和 限制，请参阅许可证。