跳到主要内容

数据截至 (上游 commit ac9c2a586ba7)

OpenMemory — 架构与原理

30 秒导读: OpenMemory 是一个自托管的"给 AI 装长期记忆"的引擎。你 add("用户喜欢暗色模式"),它 search("偏好") 能把这条捞回来——但它不只是把文本塞进向量库,而是把每条记忆归到五个认知"脑区"(情景/语义/程序/情绪/反思),用相似度 + 新近度 + 联想链路 + 标签的复合分来召回,并让记忆随时间衰减、被用到就增强。Python 与 Node 两套等价实现。

1. 这是什么(零基础也能懂)​

  • 一句话定义: OpenMemory 是一个"认知记忆引擎"——把 LLM/agent 需要长期记住的东西存进本地数据库(SQLite/Postgres),并在需要时按"人类记忆"的方式召回。

  • 解决什么问题 / 给谁用: LLM 天生健忘,一轮对话结束就忘光。给它接一个记忆系统的人通常做成 RAG:切块 → 嵌入 → 按余弦相似度检索。OpenMemory 的立场是:那只是"带 marketing 的向量库",它不知道一条记忆是事实还是情绪、有多新、有多重要、跟别的记忆怎么关联。做 agent、copilot、日记系统、编码助手的人,想让"记忆"更像大脑而不是查询缓存,就是它的目标用户。

  • 它能做什么(功能):

    • 多脑区记忆:episodic(事件)/ semantic(事实)/ procedural(技能步骤)/ emotional(情绪)/ reflective(洞察)。
    • 复合打分召回:不只看向量相似度,还叠加 token 重叠、waypoint(联想边)权重、新近度、标签匹配。
    • 衰减 + 强化:老记忆逐渐淡出;被召回的记忆重要度回升,还会顺着联想边"带动"邻居。
    • 时间知识图谱:facts 带 valid_from/valid_to,新事实自动关闭旧事实,支持"某时刻真值"查询。
    • 自托管、本地优先:默认落地一个 SQLite 文件,数据在你自己手里。
    • 接口齐全:Python SDK、Node SDK、HTTP 服务、MCP server(给 Claude/Cursor/Windsurf 当工具)、VS Code 扩展。

  • 用起来什么样: 三行,本地文件,零云配置。

    from openmemory.client import Memory

    mem = Memory()
    await mem.add("user allergic to peanuts", user_id="user123")   # 存一条
    results = await mem.search("allergies", user_id="user123")      # 语义召回

    真源码里 add/search 是 async 的:packages/openmemory-py/src/openmemory/main.py:20(Memory.add)、:27(Memory.search)。

  • 一句话直觉/类比: 把它当成 agent 的海马体:不是硬盘(什么都原样存、按 key 取),而是会"分门别类、按重要度和联想遗忘/回忆"的大脑记忆区。RAG 是"全文搜索引擎",OpenMemory 想做的是"记忆器官"。

2. 顶层全景(它大概怎么转)​

这一节给你"大盘":一条记忆写进去经过哪些部件,一次查询又怎么把它捞回来。

2.1 两条主线​

整个系统就两条端到端路径,吃透它们等于吃透 80%:

写入(add / ingest)
  文本 ──▶ 抽取(estimate tokens)──▶ 太大?拆 root+child
            │
            └─小▶ add_hsg_memory:
                    simhash 去重 ─┬─命中▶ 复用旧记忆、加分,返回
                                  └─未命中▶ 分区(classify)→ 多脑区嵌入
                                             → 存 memories/vectors → 建 waypoint 边

查询(search / hsg_query)
  query ──▶ 分区 ──▶ 逐脑区向量检索(取 k*3)
            │
            ├─置信度低?──▶ 沿 waypoint 边扩散,拉进联想到的记忆
            │
            └─▶ 对候选逐条算复合分(相似×跨区共振×惩罚 + 重叠 + 边权 + 新近 + 标签)
                  → 排序取 top-k → 命中的记忆当场强化(salience 回升、联想扩散)

2.2 部件一句话职责​

部件干什么在哪个文件(Python)
Memory 门面对外 add/search/get/delete/history/sourcemain.py(Memory)
ingest抽取文本、判断大小、root-child 拆分ops/ingest.py(ingest_document)
extractPDF/DOCX/HTML/音视频 → 纯文本ops/extract.py(extract_text)
HSG 核心去重、分区、嵌入、建链、复合打分召回memory/hsg.py(add_hsg_memory、hsg_query)
sector 分类正则打分把内容归到 5 个脑区memory/hsg.py(classify_content)+ core/constants.py(SECTOR_CONFIGS)
embed多脑区嵌入,默认 synthetic(无 API)memory/embed.py、ai/synthetic.py
vector store向量落库 + 暴力余弦检索core/vector_store.py(SQLiteVectorStore)
waypoint联想边的建立/扩散/强化/剪枝memory/hsg.py(create_single_waypoint、expand_via_waypoints)
decay后台批量衰减 + 命中强化memory/decay.py(apply_decay、on_query_hit)
dynamics跨区共振、trace 强化、联想扩散公式ops/dynamics.py
reflect聚类相似记忆、生成"反思"摘要memory/reflect.py(run_reflection)
temporal graph带时间窗的事实图谱temporal_graph/store.py、query.py、timeline.py
MCP server把 query/store/get/list/delete 暴露成工具ai/mcp.py(run_mcp_server)

注意 Python 与 Node 双实现。 packages/openmemory-py(Python)与 packages/openmemory-js(Node/TS)是同一套认知模型的两份等价实现,文件名几乎一一对应(hsg.py ↔ memory/hsg.ts,decay.py ↔ memory/decay.ts)。本文以 Python 版为主线讲解,差异处会点名 JS 侧。

2.3 主线走一遍(高层)​

  • 写: Memory.add → ingest_document 抽取并估 token → 短文本走 add_hsg_memory:先 simhash 去重,再 classify_content 分区,embed_multi_sector 对每个脑区各嵌一个向量,存进 memories/vectors,最后 create_single_waypoint 给它连一条到最相似记忆的边。
  • 读: Memory.search → hsg_query:对 query 分区、逐脑区检索、必要时沿 waypoint 扩散、对候选算 compute_hybrid_score、排序取 top-k,并对命中记忆做 on_query_hit(强化)。

3. 怎么读这套文档(阅读地图)​

由浅入深,建议顺序:

  1. 01-hsg-ingest-recall.md — 先看这个。 核心中的核心:分区、simhash 去重、多脑区嵌入、waypoint 建链,以及 hsg_query 那套复合打分。看完你就懂"一条记忆怎么进、怎么出"。
  2. 02-decay-reinforce.md — 记忆的"生命":为什么老记忆会淡、被用到为什么会变重要、联想扩散怎么让相关记忆一起回暖。这是它区别于 RAG 的灵魂。
  3. 03-temporal-graph.md — 另一条独立子系统:时间知识图谱。"CompanyX 的 CEO 2021 是 Alice、2024 变 Bob"这类会随时间变化的事实怎么建模。
  4. 04-deep-and-map.md — 存储与向量结构、值得借鉴的巧思、边界与坑、横向对比、以及给 agent 的代码地图跳转表。

每章开头都有 frontmatter 和"这章讲什么",agent 可先读 index 与各章 essence 决定下钻哪一章,不必打开全部文件。