ariel-memory

a-memory

你的 AI Agent 总会遗忘。a-memory 让它们记住。 四层 Agent 记忆，具备混合搜索和真正的知识图谱——全部存储为纯 SQLite 文件。无云服务，无外部 API。

也可通过 PyPI 获取：pip install a-memory — 可选扩展：a-memory[embeddings]，用于获取真正的多语言嵌入。

---

为什么选择 SQLite？

其他所有记忆服务都会通过云 API 传输 Agent 的数据，或要求使用单独的向量数据库。

a-memory 会将所有内容存储在你本机的 SQLite 文件中。

• 无需基础设施。 无需 Docker、数据库服务或嵌入 API 密钥。
• 数据不会离开你的网络。 可在气隙环境中运行。
• 按设计隔离各层。 用户事实和 Agent 身份永远不会共用命名空间。
• 一个目录 = 全部记忆。 使用 cp 备份，使用 rsync 同步。

---

为什么要开发它

a-memory 解决三个问题：

① Agent 自我进化 — 你的 AI 不会在不同会话间重复犯错。它会在专用的 Agent 层记住决策、错误和纠正内容，并通过每小时一次的整合扫描，将重要内容提升为长期事实。

② 持久保存用户画像 — 即使沉默数周，你的 Agent 也知道自己在与谁交谈。偏好、历史和情境信息保存在用户层，与 Agent 身份隔离。

③ 项目连续性 — project 会跟踪各项目的上下文：包含理由和结果的决策、制品映射，以及由 graphify 提供支持的代码索引——这样，新会话就能从上次结束的地方继续。

---

开始使用

pip install a-memory
a-memory          # MCP server on stdio — connect from any MCP client

服务无需安装这些模型也能运行，但隐私闸门（hooks 摄取）和图谱挖掘器需要两个 spaCy NER 模型。它们都不在 PyPI 上——en-core-web-sm 在 PyPI 上会返回 404，而 ru-core-news-sm 是无关的占位包——因此只能通过 wheel URL 安装；而 wheel URL 不能作为依赖项：PyPI 会拒绝元数据包含直接 URL 的任何发行包。运行一条命令，即可从包中已知的 URL 安装它们：

a-memory-ner                 # install (console script, ships in the wheel)
a-memory-ner --check         # report what is missing, install nothing

从源码检出目录运行 python scripts/install_ner_models.py，效果相同。

跳过这些模型也没有问题：闸门会回退并报告 degraded，而不会失败。

将 MCP 客户端指向此服务：

{
  "mcpServers": {
    "a-memory": {
      "command": "a-memory"
    }
  }
}

使用带仪表板的 HTTP 传输：

a-memory --transport http --port 8000 --dashboard

或者从源码运行：

git clone https://github.com/Cipher208/a-memory.git
cd a-memory
uv sync
uv run ariel-memory

---

七种原语

Agent 只会看到七种工具——每种意图对应一个动词，另加事件桥接器（6 个动词 + memory_hook），不会陷入工具选择困境：

原语	意图	功能
think	记住	根据重要性、情绪和关系，将内容路由到合适的层（L4 事实 / L3 事件 / wiki / 图谱）
dream	回忆	跨所有层进行混合搜索（FTS5 + 二进制嵌入 + wiki + 图谱），返回按令牌预算控制的摘要
forget	放下	具备上下文感知能力的删除，并归档至 Shadow Bin（精确 / 模糊 / 最近）——此外还提供不会写入任何内容的试运行，以及可恢复回收站所保留内容的撤销功能
evolve	成长	记录 Agent 的个性 / 规则演进
project	延续	每个项目的身份、决策日志、制品映射、代码索引
wake_up	恢复	为新会话提供一键记忆加载——一次调用获取关键内容，而不必逐步执行回忆协议
memory_hook	发送信号	事件桥接器：触发一个生命周期事件（session_started、new_message，……），让外部运行框架按自己的计划将记忆推送到 ariel

快速演示——Python MCP 客户端：

# think — routed to the right store automatically
await session.call_tool("think", {"text": "User prefers dark mode", "layer": "user"})

# dream — finds it across every store, a week later
res = await session.call_tool("dream", {"query": "dark mode preference"})
print(res["summary"])

总共有 66 种细粒度操作，分组为功能连贯的可选层级：默认提供 7 种原语；添加 context（回忆协议、/new 会话回顾、智能上下文预算、引导提示、工具输出压缩）、insight（Memory Query DSL、来源事实归因、质量循环、反思、统计）、write（类型化记忆架构、声明式规则引擎、暂存区、反事实、事件），以及 wiki 和 review（分阶段变更、memory_report_card、daily_brief）。常见的在线 Agent 工具集是一个预设——ARIEL_EXPOSE=agent（59 个工具），等同于 primitives,context,insight,write,wiki,review。其余 7 个属于管理层级：ARIEL_EXPOSE=operator（66 个）或 all。

**层级历史说明：较旧的指南仍会提到 brief 层级：**该层级已于 2026-09-07 取消——daily_brief 现已归入 review。如果文档建议传入 brief，说明它早于 1.10，该标记会被直接忽略。

⚠️ 环境变量清理提示（stdio）：MCP 客户端会向 stdio 服务传递经过清理的环境变量——在 shell 配置文件中设置 ARIEL_EXPOSE 不会生效。请在MCP 客户端配置中定义层级集合（服务条目的 env 块——参见配置指南）。服务启动时会在日志中输出解析后的工具集（tool exposure: N/M tools）——如果 Agent 报告只看到了原语，请先检查该行，然后重启客户端会话（工具列表会按会话缓存）。

---

功能

类别	内容
🧠 记忆	L1 反射（原子持久化）→ L2 会话 → L3 情景记忆 → L4 核心记忆，重要性评分，带 TTL 策略的类型化记忆种类，层级隔离；双时态事实历史（is_current 视图会全局隐藏已被取代的行，changed_since 增量轮询，可向下追溯至冷归档后仍保留的原始来源），带哈希链的 L0 日志，分为热、温、冷层；66 个工具（分层暴露；Agent 预设中包含 59 个，默认包含 7 个基础工具），包括 /recall 协议（多轴 + 披露触发条件）、会话连续性回顾（/new 恢复包）、一次调用即可执行的 wake_up、在会话简报中呈现的开放问题登记表、引导提示、工具输出压缩 + 回忆验证、溯源事实归责、Memory Query DSL（分面标签）、类型化记忆架构、声明式规则引擎、智能上下文预算（加权 token 下限）、反思、反事实、was_useful 质量闭环、运维人员诊断/修复 + 完整性评分
🔍 搜索	FTS5 + MIB 二进制嵌入 + 混合 RRF 排名、多源合并（RAG + Wiki + 情景记忆 + 核心记忆 + 图谱）、EDM/ITS 双路重排（信息增益评分，在 №11 评测中胜出）、语义去重门控（余弦相似度，可选启用）、俄语词元键规范化（pymorphy3）、反向信号降权、ACT-R 激活（按查询计算的最小-最大乘数和记忆种类权重）、嵌入路径断路器（优雅回退至哈希）、确定性检索模式、梦境摘要
🕸️ 图谱	认知知识图谱 + 时间线、类型化节点和边、BFS 遍历、1 跳 GraphRAG 扩展（感知溯源的边过滤器）、12 个自维护挖掘器（限制度数以防枢纽节点、带元数据反向链接的 wiki↔事实溯源桥接、共同检索、零结果缺口）、孤立锚点 GC、夜间缺口登记表——以及读取它的功能：现在登记表会记录每个缺口被重新观察到的次数（seen_count），并在会话简报中呈现持续时间最长的缺口，让 Agent 能看到自己尚未解答的问题，而不是无人查看的表格。可选启用 HDBSCAN 嵌入聚类，并与 louvain 结果进行一致性比较
📁 项目	决策日志（内容/原因/结果）、制品映射、graphify 代码索引——跨会话保留
⚡ 自动钩子	推送式记忆：每个 Agent 的守护进程会跟踪对话，ariel 自动保存重要内容——重要性阈值（EMA 自适应）、分阶段变更（提议 → 审查 → 应用 → 撤销）、DREAM: 标记、会话开始时注入、缺口报告、感知压缩的重新载入（漂移日志 + 挽救 + 一次性重新载入区块）、ru-NER 隐私门控（遮蔽西里尔字母中的 PERSON/ORG/LOC）。原生集成：Hermes 将 ariel 作为进程内 MemoryProvider 插件运行，MiMoCode 通过 fork-hooks 插件集成，CowAgent 通过代码级钩子集成。接线指南 →
🎯 技能	技能 = 记忆：Agent 可读取的 Markdown 页面（一级 skill wiki 类型）、渐进式披露（wiki_list → wiki_search → wiki_read，并加载相关事实）、4KB lint 上限、从 DREAM: skill: 情景记录中晋升、跨 Agent 共享 SSOT 同步、由使用情况驱动的强化——技能指南 →
🔐 安全	使用 NaCl SecretBox（XSalsa20-Poly1305）对认证/事务秘密进行信封加密、主密钥链、速率限制
🛠️ 运维	自动备份 cron、事务回滚模式、Prometheus 指标、只读副本、每小时自维护（衰减 + 整合 + 自动 VACUUM）
🌐 Wiki	由 FTS5 索引的 Markdown 文件——可在 Obsidian/VS Code 中编辑，通过 MCP 搜索，6 种分析视角（wiki_summarize），保存时执行架构 lint，与外部目录同步

---

架构

graph TD
    A[LLM Agent] -->|MCP Protocol| B[mcp_server]
    B --> C{Importance Scoring}
    C --> D[L1: ReflexBuffer]
    D --> E[L2: SessionStore]
    E --> F{EmotionTrigger?}
    F -->|high emotion| G[L3: EpisodicMemory]
    F -->|normal| H[L4: CoreMemory]

    B --> I[RAG Engine]
    I --> J[FTS5 Search]
    I --> K[MIB Binary Search]
    I --> L[Hybrid RRF Ranking]

    B --> M[Wiki System]
    M --> N[.md Files]
    M --> O[SQLite Index]

    B --> P[Knowledge Graphs]
    P --> Q[Epistemic Graph]
    P --> R[Temporal Graph]

    B --> S[Project Store]
    S --> T[Decisions / Artifacts / Code Index]

    U[Hourly Sweep] -->|consolidate| G
    U -->|promote| H
    U -->|auto-VACUUM| V[(SQLite)]

---

对比

	a-memory	mem0	letta (memgpt)	chroma
原生支持 MCP	✅ 7 个原语	❌ 无 MCP 服务	❌	❌
层隔离	✅ 用户与 Agent 命名空间	❌	❌	❌
仅本地运行（无云服务）	✅ SQLite — 无需基础设施	⚠️ API 或通过 Docker 自托管	❌ 需要 LLM API	✅ 本地开源版 + 云服务选项
自有语义搜索（无需 API）	✅ FTS5 + MIB 二进制混合搜索	⚠️ BM25 + 实体（依赖 LLM）	❌ 仅依赖 LLM	⚠️ 仅云服务提供混合搜索
知识图谱	✅ 带类型的节点 + 边 + 时间线	⚠️ 仅实体	❌	❌
信封加密（机密）	✅ NaCl SecretBox（认证/ saga 机密；记忆数据以明文存储在 SQLite 中）	❌	❌	❌
生命周期钩子	✅ 19 个名称（12 个用户 + 13 个 Agent 槽位），按层划分，受配置控制	有限	有限	无
自维护	✅ 每小时整合 + 自动 VACUUM	❌	❌	❌
备份 / 恢复	✅ 自动 cron + saga 回滚	❌	❌	❌

说明（2026 年 9 月）：mem0 现已提供可自托管的 Docker 镜像和托管云服务，并支持 BM25 + 实体混合搜索；chroma 已获 29k★，并在其 Cloud 层新增混合搜索 + FTS5（开源服务器仍仅支持向量搜索）。a-memory 的差异化优势仍在于：零基础设施的 SQLite（无需 Docker）、使用 NaCl 加密的认证/saga 机密、层隔离、每小时自维护，以及时间图谱时间线。

---

路线图

• 4 层记忆层级，且各层相互隔离
• 混合搜索（FTS5 + MIB 二进制嵌入）
• 知识图谱（认知 + 时间）
• 每小时执行一次整合扫描 + 数据库自维护
• mcp 2.x 原生 SDK
• 仓库更名为 Cipher208/a-memory；PyPI 包已上线（pip install a-memory）
• 端到端接通时间线（think/evolve/project 事件 + dream 最近摘要）
• Dream 周期注入 + 自动生成的 CONTEXT.md 快照（精选上下文 + 6 种 wiki 视角 + 最近事件，按层、按 Agent 区分）
• 阶段 C — 自动钩子基石（推送模型记忆：每个 Agent 的对话守护进程、外部事件分发器、重要性门控自动保存、带审查/还原功能的暂存变更、dream 标记、会话启动注入、差距报告；指南）
• 阶段 D — 感知压缩的重新水合（漂移日志 + 纳入摘要器的抢救内容 + 一次性重新水合块；MiMoCode 插件 / Hermes 原生 MemoryProvider / CowAgent 钩子 — 集成指南）
• 阶段 D — /recall 协议（多轴按比例召回：标记 → 会话 → 语义 → 扩展 → 日期；驱动 Hermes 每轮预取）
• 阶段 D — 技能即记忆（Markdown 技能作为一等 wiki 类型，渐进式披露 wiki_list → wiki_search → wiki_read，4KB lint 上限、晋升流程、共享 SSOT 同步、基于使用情况的演进 — 技能指南）
• 阶段 D — 工作记忆 + 元记忆（Agent 便笺在会话启动时重新注入、确定性反思、带加权下限的智能上下文预算、反事实笔记、was_useful 质量反馈循环）
• 阶段 D — 记忆工具 D1.2-D1.9（会话连续性回顾 + 引导提示、工具输出压缩 + 召回验证、来源溯因、Memory Query DSL、类型化记忆架构、声明式规则引擎；一致的 ARIEL_EXPOSE 层级：context / insight / write）
• 阶段 E — 加固与收尾（3 轮共 18 项）：持久性 — L1 原子持久化（temp→fsync→os.replace）+ 每实例环形文件，保护嵌入模型路径的断路器（失败 3 次 → 打开 30 秒 → 哈希回退确保召回持续可用），最小权限 wiki 根目录 + 防路径遍历的备份还原；运维 — memory_diagnose/memory_heal（数据库/迁移/L1 文件/断路器检查 + 重新迁移/重置断路器/清理），报告卡中的完整性评分，<cache:break> 标记 + 稳定内容优先的注入排序，适配提供方提示词缓存；检索 — 分面标签查询（dimension:value，同维度 OR / 跨维度 AND）、ACT-R 评分中的记忆类型权重、披露触发器（«当 X 时，显示 Y»）召回侧规则；接线 — 实际的 context_threshold/memory_pressure 发射器（Hermes 插件 + 自动钩子守护进程）、on_turn_end 事件、带还原功能的 wiki_write 暂存变更、可还原的转化级整合、memory_graph_add 上的因果链接生成器；验证 — DREAM 标记锚定到消息起始处（消除文档片段误报）、压缩后语义审计（L4 集合对事件的覆盖率）
• 阶段 F — L0→L4 流水线（双时态事实区间、支持 CLACK 导出的热/温/冷 L0 层、SHA-256 捕获去重、哈希链日志、来源追溯）
• 阶段 G — 自接线图谱（12 个确定性挖掘器：会话、标记、来源、共同检索、实体、零结果问题、wiki↔事实桥接）
• 阶段 H 收尾 — EDM/ITS 双路重排序 + 评测框架（NDCG@5、漂移分数、负向对照协议、LongMemEval-S 适配器）
• S17 第一阶段收尾 — 确定性检索模式、ENGRAM 程序性类型、AdaptiveRAG 预门控（27 项无需 LLM 的查询特征）、EMA 重要性门控、反向信号别名、SHA-256 L0 去重、零结果挖掘器、ru-NER 隐私门控
• S18-19 轮次（15 项）— 全局 is_current 视图 + changed_since 增量模式、按查询进行 ACT-R 最小-最大归一化、每块 max_chars、语义去重门控、按通道粒度划分来源、3 选项冲突约定（取代/保留/注释）、孤立锚点 GC、每夜运行的差距注册表、每 Agent 的评测框架断路器、来源边过滤器、wiki↔事实元数据反向链接、wiki_read 相关事实填充、RU 词元键（pymorphy3）、2 类文本分类试点（受标记控制）、S17 补充项 8-11（冷归档追溯、确认层、垃圾向量检测器、HDBSCAN 聚类）、B6 反枢纽度数上限
• S20 评测 — 在 MINI + LongMemEval-S（50 问题步长）上进行 №11 消融实验：完整双路方案在两个数据集上均胜出，已与已发布基线对比（GPT-4o 长上下文梯队，高于 ChatGPT-memory）；dense e5-small 第 3 次运行：在此划分上未能优于哈希方案 — 生产环境继续使用哈希方案
• 加固轮次（1.12.0） — 在写入端修复说话者层缺陷（distill_and_route 需要说话者时却读取了类型），并基于来源清理已错误标记的 65 行数据；修复类型分类器，不再将永久标签赋予测试框架样板内容或复合词（pre-commit、mergeCommit）；补上 S18 规划但从未构建的差距注册表读取器；L4 预期值改为按 L4 标准而非 L3 标准衡量（diff_gap 积压项中有 71% 都是这个错误数字导致的）；修复原本无法失败、现在能正确失败的 quality 门控 — 未固定版本的扫描器曾悄然更改其底层 JSON 架构
• README 中的截图 / asciinema 演示
• 在确定性扫描基础上加入 LLM 辅助整合
• 阶段 2 — 工具表面重设计（插槽系统、URI 键、注入/键整合 — 与 A 剩余项一同规划）
• LongMemEval 完整 500 问题划分 + 感知 dense 的阈值重新训练（已显示 e5-small 达到同等表现，但在 50 问题步长上并未胜出）

参与贡献

欢迎提交 PR！请参阅 CONTRIBUTING.md。

许可证

MIT © Cipher208

---

⭐ 如果这个项目对你有帮助，请在 GitHub 上为它点亮星标。