项目定位与核心能力

Aionforge Memory 是一个用 Rust 实现的、为 AI 代理（Agent）提供长期记忆能力的向量存储服务。它在 v0.2.0 中引入了 *Aionforge Memory agent plugin*，使记忆技能（memory skills）可被代理主动调用；随后在 v0.2.2 中将所有向量索引的默认度量方式切换为 TurboQuant cosine，以提升检索效率与稳定性。

资料来源：README.md:1-40

项目的核心抽象是一个记忆存储（Store）：对外提供向量化条目的写入、检索与索引协调能力，对内维护磁盘上的向量索引与元数据。v0.3.0 的关键修复（PR #250）使其在打开（open）阶段能够协调（reconcile）漂移的向量索引类型，作为 greenfield-tax 的临时方案，保证旧版本数据可被新版本无损接管。

资料来源：README.md:42-90

快速开始：本地构建与运行

在取得仓库后，先按照标准 Cargo 工作流进行构建与测试：

git clone https://github.com/jscott3201/aionforge-memory.git
cd aionforge-memory
cargo build --release
cargo test

资料来源：docs/getting-started.md:1-60

docs/getting-started.md 详细描述了三种典型部署形态：本地开发、Docker 容器、以及生产环境配置。开发模式下直接运行 release 产物即可启动内嵌的存储服务；启用日志时建议打开 tracing subscriber 以观察周期性的流量心跳（traffic heartbeat）。

资料来源：docs/getting-started.md:62-140

配置文件与生产模板

仓库根目录的 examples/production.toml 是一个可直接拷贝的生产环境参考配置，涵盖监听地址、存储路径、向量维度、索引类型与日志级别等关键参数。新建部署时建议从该模板起步，再按需裁剪。

资料来源：examples/production.toml:1-40

# 示例：examples/production.toml 节选
[server]
bind = "0.0.0.0:8080"

[store]
path = "/var/lib/aionforge-memory"
index_kind = "turboquant_cosine"

文档同时提示：自 v0.2.2 起，index_kind 若未显式给出，将默认为 turboquant_cosine，因此升级到该版本之后无需手动迁移已有配置文件即可享受性能改进。

资料来源：examples/production.toml:42-80

容器化部署与发布工件

仓库提供两份 Dockerfile：日常构建使用 Dockerfile（基于 rust:slim 多阶段构建），而发布镜像使用 Dockerfile.release，后者在 v0.2.2 中从 musl 切换到 glibc 运行时，并相应地把产物命名由 musl 改为 gnu，以匹配多数生产基础镜像并规避 musl 下的兼容性问题。

资料来源：Dockerfile:1-50 资料来源：Dockerfile.release:1-60

flowchart LR
    A[克隆仓库] --> B[cargo build --release]
    B --> C{运行模式}
    C -->|本地开发| D[直接运行二进制]
    C -->|生产部署| E[基于 Dockerfile.release 构建镜像]
    D --> F[读取 production.toml]
    E --> F
    F --> G[启动 Store 服务]
    G --> H[Agent Plugin 调用记忆技能]

诚实范围与已知限制

项目维护者通过 docs/honest-scope.md 明确列出已实现与未实现的能力边界，避免用户对早期版本产生过高预期。该文档强调：LLM 驱动的可选 consolidation 程序已在 v0.2.1（PR #241）中被移除，因此记忆合并行为完全由本地启发式规则决定，不依赖外部大模型。

资料来源：docs/honest-scope.md:1-80

用户在使用前应特别留意以下几点：

• 索引迁移：在升级跨越 v0.2.2 之前的数据时，Store 会在打开时执行一次性的索引类型协调（PR #250），用户无需手工干预，但需保证磁盘可写。
• CI 门禁：日常 CI 增加了 rustdoc -D warnings 闸口（PR #251），任何文档注释警告都会阻断合并；贡献者应在本地运行 cargo doc 自检。
• 发布流程：v0.1.0 引入的 tag 驱动、可闸控的发布工作流仍在持续演进，发布物下载已按平台过滤（PR #174）。

资料来源：docs/honest-scope.md:82-160

下一步

完成本地启动后，可参考数据模型心智模型指南（v0.2.1，PR #242）理解存储条目、向量与元数据之间的关系，并结合 examples/ 目录中的配置模板进行压测与调优。

资料来源：README.md:92-140

概述

aionforge-memory 是面向 AI 代理的长期记忆引擎，工程根目录采用 Cargo workspace 模式组织，整体按"CLI 入口 → MCP 协议适配层 → 存储核心"三层划分。MCP（Model Context Protocol）是连接外部 AI 代理的事实标准通道，也是 v0.2.0 引入的 *agent plugin* 的承载形态，使记忆能力可被 Claude Code、Cursor 等多种宿主复用。

工作空间布局

工程通过 Cargo.toml workspace 聚合多个职责单一的 crate，关键成员包括：

• aionforge-cli：用户面入口，提供 aionforge serve 等子命令，负责装配配置、加载 store 并把进程生命周期交给 MCP 服务。
• aionforge-mcp：纯协议层库，实现 MCP 规范的工具、资源、提示模板与 HTTP 传输，可被其他宿主直接嵌入。
• aionforge-store：底层向量与条目存储，是 CLI 与 MCP 共同依赖的核心数据面。

CLI 层只做组装、不掺杂业务规则，协议层不直接耦合 CLI，使得 MCP 服务既能作为独立二进制运行，也能作为库被其他程序内嵌调用。

资料来源：crates/aionforge-cli/src/serve.rs:1-120

MCP 服务实现

aionforge-mcp 按 MCP 三种原语（tool / resource / prompt）拆分模块，便于按职责独立演进：

服务启动时一次性声明全部能力，运行时按需路由 JSON-RPC 请求，避免冷启动开销。

资料来源：crates/aionforge-mcp/src/lib.rs:1-80、crates/aionforge-mcp/src/tools.rs:1-60、crates/aionforge-mcp/src/resources.rs:1-60、crates/aionforge-mcp/src/prompt.rs:1-40

传输层与会话模型

http_transport.rs 采用 MCP 推荐的 Streamable HTTP 传输，其设计要点包括：

• 单端点路由：所有 JSON-RPC 帧经由同一 URL 收发，简化代理侧配置；
• 长连接通道：通过 Server-Sent Events 推送服务端通知，支持增量记忆变更推送；
• 会话标识：请求头中的 Mcp-Session-Id 维系会话状态，store 句柄在请求间复用；
• 容器友好：与 v0.3.0 修复的 glibc/musl 运行时问题配合，便于跨平台部署。

该传输层让代理进程与 aionforge-memory 之间保持轻量、跨网络、可恢复的连接。

资料来源：crates/aionforge-mcp/src/http_transport.rs:1-160

插件体系与代理集成

自 v0.2.0（PR #175、#176）起，工程以 MCP 服务的形式对外发布 *Aionforge Memory agent plugin*。运行 aionforge serve 即暴露标准 MCP 端点，代理只需在自身配置中填入该端点 URL，即可获得三类能力：

1. 通过 tools 主动写入、检索、删除记忆条目；
2. 通过 resources 按 URI 浏览记忆片段与上下文快照；
3. 通过 prompt 加载预设的主动式记忆技能模板，由代理在适当时机自动触发（"proactive memory skills"）。

这种"协议即插件"的形态使 aionforge-memory 不绑定特定代理实现，符合 MCP "一次实现、多端复用" 的设计初衷，也为后续接入新代理（如其他 MCP 兼容客户端）提供零成本扩展路径。

资料来源：crates/aionforge-cli/src/serve.rs:40-90、crates/aionforge-mcp/src/prompt.rs:1-40

概述

aionforge-memory 是一个面向 agent 的嵌入式/独立可部署记忆存储子系统，提供可按 agent_id 隔离的持久化、检索与回写能力。本页描述其记忆数据模型的核心抽象、捕获（capture）阶段的写入路径，以及检索（retrieval）阶段的回放路径，三者共同构成一次完整的"先存后取"会话闭环。

整个系统围绕"agent 维度 + 记忆分槽（slot）"展开：每个 agent 拥有独立的 store 文件夹，内含 core、procedural、capture 等分块；上层通过 CLI/HTTP/gRPC/Plugin 暴露统一 API，下层由 store、vector index、tracing 三大组件完成实体落地与可观测性。资料来源：docs/data-model.md:1-40

记忆数据模型

记忆被划分为三类语义明确的槽位，分别承担"身份"、"技能"与"事件片段"三种职责。

• Core Memory（核心记忆）：以自由文本描述 agent 的身份、用户偏好与人物设定，作为检索时默认串入上下文的稳定基线。资料来源：docs/core-memory.md:1-40
• Procedural Memory（程序记忆）：存放"什么时候调用什么技能"的可执行经验条目，包含触发条件、动作、效果评估字段，便于后续匹配复用。资料来源：docs/procedural-memory.md:1-40
• Capture Memory（捕获记忆）：记录 agent 实际执行过的对话/工具调用片段，以时间序存储并向量化，供相似度检索回顾。资料来源：docs/capture.md:1-40

每次写入都会同时维护两条通道：结构化日志（用于回放与去重）与向量索引（用于语义检索）。在 v0.2.2 起，所有向量索引默认使用 TurboQuant cosine 度量；v0.3.0 起，store::open 还会对"漂移的向量索引 kind"做一次性对账修复，作为过渡期的 greenfield-tax 缓解措施。资料来源：docs/data-model.md:50-120

捕获数据流

捕获阶段负责把外部事件（用户消息、工具输出、agent 行为）落地为 capture 条目。其流水线为：

flowchart LR
    A[外部事件] --> B[capture API]
    B --> C[去重 / 规范化]
    C --> D[结构化日志 append]
    C --> E[向量索引 upsert]
    D --> F[(agent store)]
    E --> F

关键点：

1. 写入按 agent_id 路由到独立目录，避免跨 agent 串扰。资料来源：docs/capture.md:30-80
2. 文本在向量化前完成切分与归一化，确保索引重建时仍能复现同样 hash。资料来源：docs/capture.md:80-130
3. v0.2.1 移除了"可选的 LLM 合并程序"，即 capture 路径不再依赖外部 LLM 调用，全部使用确定性合并规则。资料来源：docs/consolidation.md:1-40

检索数据流

检索阶段将一次外部查询映射为对三类槽位的并行回放，再统一排序返回。其流水线为：

flowchart LR
    Q[查询 query] --> R[embedding]
    R --> S1[core 串入]
    R --> S2[procedural 匹配]
    R --> S3[vector ANN 检索]
    S1 --> M[merge / rank]
    S2 --> M
    S3 --> M
    M --> O[上下文 + 来源]

要点：

• 检索默认将 core 全文串入，再叠加 procedural 的触发匹配结果与 capture 的 ANN 命中，三者合并后产出"上下文 + 来源引用"。资料来源：docs/retrieval.md:1-60
• 向量检索使用与写入一致的 TurboQuant cosine 度量，分数解释与召回口径因此跨版本一致。资料来源：docs/retrieval.md:60-110
• 日志层为每次检索写入 tracing span，并由 v0.3.0 引入的周期心跳输出，辅助排查"为什么这次没召回"。资料来源：docs/retrieval.md:110-160

跨阶段的语义一致性

为了让"先存后取"自洽，系统在多个环节保持可对账：

• 写入即索引：capture 写入会同步生成向量条目，避免"日志有但索引无"的不可见状态。资料来源：docs/capture.md:130-180
• kind 对账：v0.3.0 的 store::open 会在启动时检测漂移索引并重建，使历史数据对当前检索口径可见。资料来源：docs/data-model.md:120-160
• 可观测性贯通：捕获与检索都进入同一 tracing 订阅器，便于将一次会话的"写入—检索—回放"在日志层串联。资料来源：docs/data-model.md:160-200

综上，aionforge-memory 通过"分槽数据模型 + 同步写入双通道 + 检索三路合并"的设计，把 agent 所需的身份、技能、事件三类记忆统一在同一可对账、回放友好的数据流中。

安全模型与威胁假设

security-model.md 定义了服务的总体安全姿态：进程默认以最小权限运行，监听端口仅暴露必需的 gRPC/HTTP 接口，磁盘上的向量索引、Manifest 与 WAL 在静态时依赖宿主文件权限进行隔离。

威胁模型覆盖以下类别：

• 未授权读取：外部攻击者通过网络或本地文件系统读取持久化数据
• 未授权写入：低权限调用方尝试修改其他命名空间的向量或元数据
• 索引漂移：重启或异常断电后，向量索引类型（kind）与 Manifest 描述不一致
• 依赖投毒：构建产物中的第三方 crate 被替换或篡改

针对上述威胁，安全模型要求：所有对外接口强制走命名空间鉴权、Manifest 与索引在打开时进行类型对齐检查（参见 v0.3.0 的 feat(store): reconcile drifted vector-index kinds on open），发布产物则通过 cargo-deny 与 provenance 签名进行供应链把关。资料来源：docs/security-model.md:1-40

信任边界与命名空间授权

trust-model.md 与 namespace-authorization.md 共同描述了多租户下的信任分层。系统将信任划分为三层：

命名空间授权基于显式的 allow 列表与 token 校验：客户端在调用 Open / Put / Query 前必须提供命名空间身份，跨命名空间的访问会被 cross-family-guard.md 描述的守护逻辑拒绝。cross-family-guard.md 同时规定了"族（family）"的概念——同一族内的命名空间可以共享向量度量类型与 Embedding 模型，而跨族操作必须经过显式授权与度量转换。资料来源：docs/trust-model.md:10-60、docs/namespace-authorization.md:20-80、docs/cross-family-guard.md:1-45

供应链签名、证明与晋升

provenance-signing.md 与 attestation-and-promotion.md 描述了从构建到运行时的"可信链"。每次发布都会生成：

1. 构建证明（provenance）：由 CI 记录 commit、依赖锁文件与构建环境指纹
2. 制品签名：基于 Sigstore / cosign 对二进制镜像与 release tarball 签名
3. 晋升守门（promotion gate）：测试、rustdoc (-D warnings)、cargo-deny 全部通过后才允许打 tag

flowchart LR
    A[源码 + Cargo.lock] --> B[CI 构建]
    B --> C[rustdoc + cargo-deny]
    C --> D[生成 provenance]
    D --> E[cosign 签名]
    E --> F[Tag 晋升]
    F --> G[运行时启动校验]

运行时启动阶段会重新校验签名与 provenance 是否与当前二进制匹配，任何不一致都会导致进程以非零码退出。这一机制与 v0.1.0 引入的"tag-driven, gated releases via a reusable workflow" 一脉相承。资料来源：docs/provenance-signing.md:1-55、docs/attestation-and-promotion.md:15-70

运维可观测性与 Embedding 配置

运维侧的核心约定由 security-model.md 与 release notes 中的 logging 演进共同支撑。v0.3.0 引入了基于 tracing subscriber 的结构化日志以及周期性 traffic heartbeat，使运维方可以观察到 QPS、错误率与命名空间活跃度。

Embedding 配置方面，从 v0.2.2 起所有向量索引默认采用 TurboQuant cosine 度量，这意味着：

• 客户端在 Put/Query 时无需显式指定度量类型即可享受 cosine 语义
• 跨族查询在度量转换路径上具备一致性保障
• 索引重建与漂移修复（drifted-kind reconciliation）会保持度量不变，避免召回差异

部署方面，发布镜像自 v0.2.2 起统一使用 glibc 运行时并以 gnu 命名 artifact，避免 musl 兼容性问题导致的启动失败。运维方可结合心跳日志与命名空间授权日志共同定位异常访问来源。资料来源：docs/security-model.md:60-95、docs/namespace-authorization.md:85-120、docs/attestation-and-promotion.md:80-110

提示：本页面描述的是 aionforge-memory 当前主线（v0.3.0）的行为；自定义 Embedding 模型或非默认度量时，应同时复查 cross-family-guard.md 与对应命名空间的授权策略。

Pitfall Log / 踩坑日志

项目：jscott3201/aionforge-memory

摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 依赖 Docker 环境。

1. 安装坑 · 依赖 Docker 环境

• 严重度：medium
• 证据强度：runtime_trace
• 发现：安装/运行入口包含 Docker 命令：docker run --rm -p 127.0.0.1:3918:3918 -v aionforge-data:/data -e AIONFORGE_EMBEDDER__ENABLED=false ghcr.io/jscott3201/aionforge-memory:0.3.0
• 对用户的影响：非工程用户可能没有 Docker，启动成本明显增加。
• 复现命令：docker run --rm -p 127.0.0.1:3918:3918 -v aionforge-data:/data -e AIONFORGE_EMBEDDER__ENABLED=false ghcr.io/jscott3201/aionforge-memory:0.3.0
• 证据：identity.distribution | https://github.com/jscott3201/aionforge-memory | docker run --rm -p 127.0.0.1:3918:3918 -v aionforge-data:/data -e AIONFORGE_EMBEDDER__ENABLED=false ghcr.io/jscott3201/aionforge-memory:0.3.0

2. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/jscott3201/aionforge-memory | host_targets=mcp_host, claude_code, claude, cursor, codex, chatgpt

3. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/jscott3201/aionforge-memory | README/documentation is current enough for a first validation pass.

4. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/jscott3201/aionforge-memory | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/jscott3201/aionforge-memory | no_demo; severity=medium

6. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/jscott3201/aionforge-memory | no_demo; severity=medium

7. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/jscott3201/aionforge-memory | issue_or_pr_quality=unknown

8. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/jscott3201/aionforge-memory | release_recency=unknown