ori-memory

Ori Mnemos

面向 AI Agent 的开源持久化记忆基础设施。

Ori 将人类认知建模为知识图谱上的数学模型：ACT-R 中的激活衰减；沿 wiki-link 边传播的激活；基于检索模式的赫布共现；作用于检索本身的强化学习；以及通过子问题分解进行的递归图遍历。系统会学习哪些内容重要、遗忘哪些内容不重要，并优化自身的检索流程。

在会话、客户端和设备之间持久保存记忆。零基础设施检索在基准测试中达到现有方案的水平，且在多个方面显著优于它们——并且你的每一个字节都归你所有。磁盘上的 Markdown。作为图边的 Wiki-link。用 Git 进行版本控制。不受数据库绑定，无云依赖，不受供应商控制。

v0.7.0 · npm · 论文 · Apache-2.0

---

使用方法

Ori 是基于同一索引的三个入口。Markdown 才是事实来源；索引是派生数据。学习所得的部分——Q 值、LinUCB 臂、检索历史——并非派生数据，因此删除任何内容前，请先导出（参见何时重建）。

CLI

npx ori init          # scaffold a vault
npx ori index build   # derive the index
npx ori explore "…"   # navigated retrieval
npx ori sql "…"       # read-only SQL over the index

MCP 服务 — ori serve，在客户端配置中注册。这是 Agent 使用它的方式。

库 — recall 是 CLI 和 MCP ori_recall 工具共同使用的同一个接入点，因此程序化调用路径与 Agent 调用路径不会出现偏差。

import { recall } from "ori-memory";

const res = await recall("./vault", "what did we decide about caching?", { limit: 5 });
for (const hit of res.data.results) console.log(hit.title, hit.score);

对于已组装好向量、图指标和配置的调用方，也导出了 searchComposite；recall 会为你完成这些组装工作。

导出接口刻意保持精简，并遵循 semver 契约；src/core 的其余部分均为内部实现。0.8.0 之前的版本没有 main 和 exports，因此直接导入会报错，且不存在库调用路径——但 CLI 和 MCP 路径始终可用，现有用户不受影响。

对于需要定位二进制文件并启动它，而不是将其链接到自身代码中的调用方，ori-memory/cli 会解析到 CLI 入口。预期用法是对其调用 require.resolve；导入它会运行 CLI。

基准测试

ForgetEval — 它能按要求遗忘吗？

deeplethe/lethe，bench/forgeteval/， MIT。**无需 API 密钥、无需网络、无需 LLM 评判器。**评分器是 GeneratedCase.run() 中约 20 行的确定性子串检查：它会自行调用 recall_texts(query, k=10)，拼接排名前 10 的结果，并检查 must_contain / must_not_contain。生成过程使用模板和 random.Random(42)。可选的 LLM 钩子默认为 llm=None，且未使用。

类别	Ori	要求
替换	200 / 200	替换一条事实，旧值不得再出现
衰减	200 / 200	release(query) — 按需软驱逐
失忆	198 / 200	驱逐一个主题，保留旁观内容
清除	182 / 200	硬删除，必须彻底移除原文秘密
漂移	198 / 200	连续进行两次替换，只保留最后一条
总体	978 / 1000（97.8%）	生成 1,000 个用例，种子为 42

未针对测试集进行拟合：未见种子下的结果为 97.2%（种子 7）和 98.0%（种子 123）。修复的是匹配器中的结构性缺陷，而非针对个别用例的补丁。 请以 35% 的基准线衡量这些结果，而不是以零为基准。 评测器会在前 10 条结果上检查 must_contain 和 must_not_contain；而当 must_contain 为空时——也就是所有 decay 案例，以及 200 个 purge 案例中的 150 个，共 1,000 个案例中的 350 个——一个什么也不返回的系统就能空手通过。一个接受写入、却从不返回任何内容的空适配器，得分为 350/1000 = 35%，而且在整个 decay 系列中得分为 100%。在真正具有区分度的 650 个案例中，Ori 的得分是 628/650 = 96.6%，其 purge 得分则从 91% 降至 64%，这才是它真正的弱项。已公布的 LangMem 99.5 / Lethe 99.3 / Mem0 88.8 是全套评测得分，同样包含这部分基准分。 请参阅 docs/falsification/forgeteval-validity.md。

系统	模板	对抗
LangMem	99.5	—
Lethe v1	99.3	63.4
Ori Mnemos	97.8	65.7
Mem0	88.8	68.3
MemPalace	0	—

当天早些时候，Ori 在这项基准测试中的得分还是 0/1000。 这不是低分，而是结构性归零。ForgetEval 的适配器协议有三个可选操作：supersede、release 和 purge，而 Ori 一个都没有：在 src/ 中命中次数为零。所有案例都不适用。Ori 已有的 ACT-R 衰减曲线和 Ebbinghaus 曲线是排序时的先验，而没有基准测试测量这些；ForgetEval 所谓的“decay”系列指的是显式调用 release(query)。src/core/forget.ts 有 305 行代码，一天之内就补齐了整个缺口，这是本页最值得关注的数字。

这张表不是排名，把它读成“第三名”并不恰当。

ForgetEval 的代码位于 deeplethe/lethe 中——基准测试和得分最高的系统来自同一组织，所在仓库只有 14 个 star。模板栏只有四个条目，其中一个（MemPalace）因为完全没有提供删除原语，得分按设计就是 0。其余两个则接近满分。在对抗层，Ori 在 14 种配置中排第 5，处于论文自有 McNemar 检验判定为噪声的 63–68% 区间内（χ²=0.125，p=0.724）；论文的原话是“该基准反映的是权衡，而非赢家”。唯一具有统计显著性的比较是 Ori 与 Lethe 在模板集上的结果，z=2.81，p=0.005——Lethe 确实领先。

哪些系统缺席，比谁排在前面更重要。 Supermemory（30.6k 个 star，260 万美元种子轮融资）提供 POST /v4/memories/forget-matching——支持自然语言遗忘，并带有 dryRun、threshold、maxForget 和审计句柄——以及支持版本控制的 PATCH 替代操作。与这里所有受测系统相比，它的控制平面规范得更好，而且几乎可以逐字映射到适配器协议上。但它从未接受过基准测试。Hindsight（24.0k）、Cognee（30.8k，因 API 不兼容而排除）、MemOS（11.5k）和 Honcho（7.3k）也都没有接受过测试。

因此，诚实的说法不是 Ori 比其他系统更擅长遗忘，而是Ori 无需 API 密钥，就能离线遗忘；而这个领域根本不知道自己的遗忘能力如何：

我们检查了 15 个 Agent 记忆系统。没有一个公布过针对自家系统的遗忘基准测试。 现有五项此类基准测试——ForgetEval、 Memora/FAMA、MemoryAgentBench-SF、StateMemBench、MemLeak——供应商一个也没有引用。现有的所有遗忘能力数据，都是由竞争对手或外部机构得出的。

解读对抗栏时，还要注意另一点。 其中 385 个案例有 253 个，只有在通过供应商自家系统的测试后才被纳入；adversarial.py 中将其标注为“经 Oracle 验证（Lethe / Lethe+LLM 能通过该案例）”。作者自己进行的盲测 77 案例外部子集，将整个领域的得分从 63–68% 区间降至 28–33%，这说明内部测试集明显更容易。如果一项基准测试的纳入筛选条件是“测量者自己的系统能解决该问题”，它就无法给测量者排名。

复现：

git clone https://github.com/deeplethe/lethe && cd lethe
cp <ori>/bench/forgeteval_ori_adapter.py bench/forgeteval/ori_adapter.py
export ORI_BRIDGE=<ori>/bench/forgeteval-bridge.mjs
python -m bench.forgeteval.run --adapter ori --suite template --scale 200 --seed 42

四分钟，1,000 个案例，$0.00。由于测试框架每个案例会发起约 10 次调用，而每次调用都启动 CLI 子进程会让解释器启动耗费数小时，因此适配器通过 NDJSON 与常驻 Node 进程通信。

HotpotQA — 多跳检索

与 Mem0 进行正面对比。两个系统索引了相同的文档，并在同一轮运行中回答了相同的问题。

指标	Ori Mnemos	Mem0 1.0.6	Δ
Recall@5	0.87	0.29	3.0×
MRR	0.91	0.42	2.2×
检索 F1	0.51	0.26	2.0×
答案代理指标	0.73	0.34	2.1×
基础设施	Markdown + SQLite	Redis + Qdrant + 云	—

n = 50，单次运行，不对随机种子取平均，topK = 5。Mem0 版本为 1.0.6（2026 年 3 月）； 尚未重新运行 2.x，因此请将其视为某一时间点的对比，而非当前对比。 原始输出：bench/results/，可通过 bench/hotpotqa-eval.ts 和 bench/mem0-hotpotqa.py 复现。

这些并非 HotpotQA 的官方指标，不得与 HotpotQA 榜单进行比较。 官方评分器 hotpot_evaluate_v1.py 使用其自身的 normalize_answer 报告答案 EM/F1，并计算基于 (title, sentence_id) 对的支持事实 F1，以及联合 EM/F1。上表是 bench/hotpotqa-eval.ts 中定义的标题级检索指标，而“答案代理指标”根本不是 HotpotQA 指标——它是检索文本中黄金答案的 token 召回率。这项对比仅在一个方向上有效：Ori 和 Mem0 使用同一套评估流程处理了相同的问题，因此两列数值之间的比率有意义。绝对数值则不能用于其他场景。

在 n = 50 时，Recall@5 的 Wilson 95% 置信区间为：Ori [0.75, 0.94]，Mem0 [0.18, 0.43]。两者没有重叠，因此差距是真实的，但表中保留两位小数的精度并不可靠：应将 0.87 理解为“0.80 多”。

此处未报告延迟。评估流程不会记录延迟，因此任何数值都只能是回忆所得，而非实际测量。实际测得的是：Ori 可基于 Markdown 和本地 SQLite 索引回答问题，无需 API 密钥，也无需网络。

LoCoMo — 长期对话记忆

10 段对话中的 1,536 个问题。 检索采用 BM25、嵌入和 PageRank 融合，取前 5 个结果。不需要 API 密钥，也不访问网络：答案列是 抽取式代理指标，即真实答案与检索文本之间的 token 召回率，而非生成的答案。

类别	召回率	答案 F1	MRR	n
开放域	0.943	0.929	—	841
单跳	0.863	0.758	—	321
多跳	0.528	0.670	—	282
时间	0.565	0.478	—	92
总体	0.827	0.819	0.729	1,536

原始输出：bench/results/locomo-eval-2026-09-19T22-37-31-698Z.json。 使用 npx tsx bench/locomo-eval.ts --json 复现；运行耗时 48 秒。

多跳和时间类别表现较弱，本文如实报告。

本文件的早期版本有两处更正，均于 2026-09-19 发现：

• 之前报告的问题数为 695，总体召回率为 0.687。该子集悄然排除了开放域类别，而该类别占 1,536 个问题中的 841 个，超过基准测试的一半。各类别的数值大致正确；“总体”则是对人为挑选的三个类别取平均。bench/README.md 又列出了第三组数值（召回率为 44.7%），但无法通过当前测试框架复现。现在只保留一组数值，并附上运行文件。
• 2026-09-19 的运行结果与 2026-07-22 的运行结果在小数点后三位一致，因此这些数值在 09ac45d 中的检索指标修复和 72fdd13 中的 lambda 调整后仍然稳定。

特意不提供与已发布 LoCoMo 排行榜的对比表。 那些是由 LLM 评判的分数；上述数据则是 token F1。两者衡量的并非同一指标，把它们放在同一列会凭空编造排名，而非如实报告。本 README 的早期版本就犯过这个错误。

LoCoMo 本身存在已知缺陷。一项独立审计发现，6.4% 的问题答案键有误，因此理论上限为 93.57%；而标准的 gpt-4o-mini 评判器会接受 62.81% 的刻意错误答案。至少有一个已发布分数超过了数学上限。在这个基准测试中，接近的结果无论朝哪个方向都只能算弱证据，因此本文会报告这些数据，但不会将其作为重点。

LongMemEval-S — 检索，500 个问题

按会话粒度计分，470 个计分问题（官方评分器会排除 30 个弃答问题）。无需 API 密钥、无需网络、无需 LLM 评判器——该基准自带的评分器只导入 sys、json 和 numpy。

	recall_any@k	recall_all@k	ndcg_any@k
@1	0.866	0.300	0.866
@5	0.966	0.830	0.884
@10	0.981	0.904	0.898

recall_all@k 要求前 k 个结果中包含所有金标准会话；recall_any@k 只要求包含一个。官方摘要报告 recall_all@5 和 ndcg_any@5。

与同一基准上使用相同嵌入器发布的数据相比，以下三种系统均为零 API 调用：

System	Embedder	R@1	R@5	R@10
MemPalace（原始）	all-MiniLM-L6-v2	80.6%	96.6%	98.2%
Lethe v1	all-MiniLM-L6-v2	85.4%	97.4%	99.0%
Ori Mnemos	Xenova/all-MiniLM-L6-v2	86.6%	96.6%	98.1%

Ori 在 @1 领先，到 @10 时则持平。**这项结论的范围没有表面看起来那么大。**针对 MemPalace 的一项独立分析（arXiv:2604.21284）得出结论：其 96.6% 的 R@5「体现的是 ChromaDB 默认嵌入模型（all-MiniLM-L6-v2）应用于原文文本块时的性能」，并且可以通过最简 ChromaDB 配置复现。在 k=5 时，该指标已趋于饱和，主要衡量的是嵌入器，而三行使用的是同一个嵌入器。客观地说，Ori 的检索并非瓶颈，这一维度已无法区分各系统。

Ori 的 recall_any@5 为 0.9660，与 MemPalace 发布的 96.6% 在三位有效数字上相符。这只是巧合，并非照搬数据；完整的逐题输出已提交。

与 LoCoMo 一致，表现较弱的类别包括多会话（recall_all@5 为 0.653）和时间推理（0.772），而两种单会话类型均为 1.000。多跳和时间推理是 Ori 在两个基准上都表现较弱的领域；两项独立测量结果相互印证，而非噪声。

复现：

npx tsx bench/longmemeval-eval.ts --data <longmemeval_s_cleaned.json>
python bench/longmemeval-score.py <rankings.json> <path/to/LongMemEval>
python <LongMemEval>/src/evaluation/print_retrieval_metrics.py <rankings.jsonl>

11 分钟，500 个问题，$0.00。bench/longmemeval-score.py 导入基准自带的 evaluate_retrieval，而非重新实现 recall_all@k，因此这些结果采用的是作者定义的指标。

---

快速开始

npm install -g ori-memory
ori init my-agent
cd my-agent

连接到你的 Agent：

# Full adapters — auto-orient at session start, capture at session end
ori bridge claude-code --vault ~/brain                 # hooks + MCP + CLAUDE.md
ori bridge hermes --vault ~/brain                      # native plugin + MCP + HERMES.md
ori bridge opencode --vault ~/brain                    # plugin + MCP + AGENTS.md

# MCP-only adapters — tools available, no lifecycle automation
ori bridge cursor --vault ~/brain                      # .cursor/mcp.json
ori bridge codex --vault ~/brain                       # ~/.codex/config.toml

# Any MCP client
ori bridge generic --vault ~/brain                     # prints config for manual setup

Claude Code、Hermes Agent 和 OpenCode 支持完整的生命周期集成——Agent 在会话开始时进行状态定位，在会话结束时捕获洞见，并在写入时验证笔记。Cursor、Codex 和其他 MCP 客户端可以使用全部 16 个工具，但需要自行管理会话生命周期。

手动配置 MCP（适用于任何支持 MCP 的客户端）：

{
  "mcpServers": {
    "ori": {
      "command": "ori",
      "args": ["serve", "--mcp", "--vault", "/path/to/brain"],
      "env": { "ORI_VAULT": "/path/to/brain" }
    }
  }
}

开始一个会话。Agent 会自动接收其身份信息，并在首次运行时开始引导流程。

---

最新动态

v0.6.0 — 导航式递归。ori explore 不再返回扁平的综合结果。Agent 可以看到分解树——哪些分支产生了结果，哪些走入了死胡同——并自行引导遍历过程。新增会话命令：explore-start、explore-expand、explore-conclude。预算是引导，而非限制：预算宽限耗尽时会明确提示可扩展预算。四信号融合之上新增交叉编码器重排序阶段。RMH 约束 2 从部分实现变为真正落实。

$ ori explore-start "why did we choose SQLite over postgres"

exploration e7f2 — 3 branches
├─ [1] storage engine tradeoffs        4 notes, strong signal
├─ [2] deployment constraints          2 notes
└─ [3] prior migration decisions       dead end — no notes

next: ori explore-expand e7f2 1   |   ori explore-conclude e7f2 --answered

**v0.5.6 — OpenCode 桥接。**完整的生命周期集成：首次运行引导、自动会话捕获、笔记验证、多知识库支持。ori bridge opencode——只需一条命令。

**v0.5.5 — 艾宾浩斯温度。**只访问过一次的笔记会快速衰减（半衰期约 7 天）。在多个会话中访问过的笔记则会深度嵌入（最长约 28 天）。短期记忆和长期记忆在结构上截然不同。

完整历史记录请参阅 CHANGELOG。

---

递归记忆框架

Ori 是 递归记忆框架（RMH）的首个实现。RMH 定义了一组约束，规定 AI Agent 的持久记忆应如何运作。

其核心理念源自递归语言模型（Zhang、Krassa 和 Khattab，2026）。RLM 不把上下文视为要塞进窗口的输入，而是视为一个需要探索的环境。模型不会得到一张更大的办公桌，而是长出双腿，走进图书馆。RMH 将同一原则应用于持久记忆。

三项约束构成了这一框架：

1. 检索必须遵循图结构。 记忆不是扁平的向量存储。笔记是节点，Wiki 链接是边。检索会遍历结构——使用 α=0.45 的个性化 PageRank、沿边传播激活，并进行感知社区结构的遍历。图的拓扑结构会影响检索结果。

2. 未解决的查询必须递归处理。 当单次检索不足以解决问题时，系统会将问题拆解为若干子问题，分别检索，再综合结果。当新一轮检索不再发现新信息时，收敛检测会停止递归。这正是 ori explore 的工作方式。

3. 每次检索都必须重塑图结构。 检索并非只读操作。共同检索到的笔记之间会形成共现边（赫布学习）。Q 值会根据检索到的笔记是否真正有用而更新。图会从使用方式中学习——每次查询都会让下一次查询变得更好。

大多数记忆系统将检索视为搜索。RMH 则将检索视为导航、递归和学习——在一张随每次会话不断演化的图上进行。

阅读完整论文：介绍递归记忆框架

---

功能说明

• 持久身份。 Agent 状态——名称、个性、目标、方法论——以纯 Markdown 格式存储，并通过 MCP 指令在会话开始时自动注入。无需重新配置，身份即可在客户端切换、机器迁移和模型更改后持续保留。

• 知识图谱。 每个 [[wiki-link]] 都是一条有向边。支持 PageRank 权威度、Louvain 社区检测、中介中心性、桥接检测，以及孤立链接和悬空链接分析。可通过 MCP 工具和 CLI 查询结构。

• 三种记忆空间。 身份（self/）以 0.1 倍速衰减——几乎不会淡去。知识（notes/）以 1.0 倍速衰减——随相关性而生，也随相关性而灭。操作（ops/）以 3.0 倍速衰减——快速燃尽并自行清理。这种区分体现在架构中，而非仅仅是表面形式。

• 认知遗忘。 笔记依据 ACT-R 基础水平学习方程衰减，而非使用随意设定的 TTL。用过的笔记会保持活跃。它们的邻近笔记会通过 wiki 链接边上的扩散激活保持热度。结构上至关重要的节点由 Tarjan 算法保护。ori prune 会在归档任何内容之前分析完整的激活拓扑。

• 四信号融合。 通过按分数加权的倒数排名融合，将语义嵌入、BM25 关键词匹配、个性化 PageRank 和关联热度融合。意图分类（情景、程序、语义、决策）会自动调整信号权重。

• 抑制流水线。 通过消融测试验证的三个融合后阶段：重力抑制会将与查询词完全不重合的余弦相似度幻影减半；枢纽抑制会施加 P90 度数惩罚，防止地图笔记主导结果；解析度增强则优先呈现可执行的知识（决策、经验总结），而非被动观察。

• 学习式检索（v0.4.0）。 三个智能层可逐次提升会话间的检索质量，综合了 63 个研究来源。详见下文的检索智能。

• 捕获-晋升流水线。 ori add 会将内容捕获到收件箱。ori promote 会进行分类（想法、决策、经验总结、洞见、阻碍因素、机会）、检测链接并推荐领域。包含 50 多种启发式模式。可选用 LLM 增强。

• 零云依赖。 通过在进程内运行的 all-MiniLM-L6-v2 提供本地嵌入。使用 SQLite 存储向量和智能状态。所有内容都在你的文件系统中。核心功能无需 API 密钥。

---

检索智能（v0.4.0）

三个学习层可随时间提升检索质量，无需手动调优。综合了强化学习、信息检索、认知科学和多臂老虎机理论领域的 63 个研究来源。

第 1 层 — Q 值重排序

笔记根据会话结果通过指数移动平均更新获得 Q 值。随着时间推移，真正有用的笔记会逐渐上升，噪声则会沉降。

信号	奖励	触发条件
前向引用	+1.0	你在新内容中 [[link]] 一个检索到的笔记
检索后更新	+0.5	你编辑刚检索到的笔记
会话内再次检索	+0.4	同一笔记出现在不同查询的结果中

RRF 融合后，阶段 B 会通过相似度分数与学习所得 Q 值的 lambda 混合，对候选集重新排序，并加入探索奖励，确保检索不足的笔记仍有机会被发现。笔记在展示后一直未被使用，奖励就会逐渐缩小；一旦笔记获得过奖励，就会保留完整奖励，因此，已被使用的笔记排名永远不会低于相关性相同但从未被看到的笔记。累积偏差上限（MAX=3.0，压缩系数=0.3）可防止分数失控膨胀。

第 2 层 — 共现边

同时检索到的笔记之间会逐渐形成边——这是知识图谱上的 Hebbian 学习。边权重通过 NPMI 归一化（衡量超出基准频率的真实关联）、GloVe 幂律频率缩放，以及带强度累积的 Ebbinghaus 衰减计算（频繁共同检索的笔记对衰减更慢）。

每个节点的 Turrigiano 稳态机制可防止枢纽笔记吸收所有边权重。文献耦合会根据现有 wiki 链接结构为第 0 天的边提供初始权重，无需等待任何查询。

组合后的 wiki 链接与共现图会馈入 Personalized PageRank 游走（HippoRAG，α=0.5），从而找出仅靠语义搜索永远无法发现的笔记。

第 3 层 — 阶段元学习

每个可选的流水线阶段（PageRank、热度、枢纽抑制、共现 PPR）都由 LinUCB 上下文老虎机封装，并使用 8 维查询特征向量。系统会学习哪些阶段适用于哪些查询类型，并自动跳过持续造成负面影响的阶段。

每个阶段有三种决策：运行 / 跳过 / 弃权（提前停止流水线）。考虑成本的阈值确保成本较高的阶段必须达到更高标准。必要阶段（语义搜索、BM25、RRF 融合、Q 重排序）绝不会跳过。Q 重排序之所以必要，是因为老虎机的奖励衡量结果形态和术语召回率，无法判断某条笔记是否被使用。ACQO 两阶段课程会在探索期间（前 50 个样本）运行所有阶段，然后再进行优化。

会话学习循环

Query → Retrieve → Use (cite, update, create) → Reward signals
  ↓                                                    ↓
  Co-occurrence edges grow                Q-values update (session-end batch)
  ↓                                                    ↓
  Stage meta-learner updates              Better retrieval next session

所有更新都会在会话结束时按顺序于单个 SQLite 事务中完成：共现 → Q 值 → 阶段学习。

---

技术栈

Layer 6: MCP Server                    16 tools, 5 resources — any agent talks to this
Layer 5: Recursive Exploration         PPR graph traversal, sub-question decomposition, convergence detection
Layer 4: Retrieval Intelligence        Q-value reranking, co-occurrence learning, stage meta-optimization
Layer 3: Dampening Pipeline            gravity, hub, resolution — ablation-validated
Layer 2: Four-Signal Fusion            semantic + BM25 + PageRank + warmth → score-weighted RRF
Layer 1: Knowledge Graph + Vitality    wiki-links, ACT-R decay, spreading activation, zone classification
Layer 0: Markdown files on disk        git-friendly, human-readable, portable

16 个 MCP 工具 · 5 个资源 · 20 条命令行命令 · 874 项测试

---

Token 成本

不使用检索时，每个问题都需要将整个知识库载入上下文。使用 Ori 后，成本保持不变。

知识库大小	不使用 Ori	使用 Ori	节省
50 条笔记	10,100 tokens	850 tokens	91%
200 条笔记	40,400 tokens	850 tokens	98%
1,000 条笔记	202,000 tokens	850 tokens	99.6%
5,000 条笔记	1,010,000 tokens	850 tokens	99.9%

使用 Ori 时，典型会话的成本约为 ~$0.10。不使用时：~$6.00+。

---

架构

                          Any MCP Client
                    (Claude, Cursor, Windsurf,
                     Cline, Hermes, custom agents, VPS)
                              │
                        MCP Protocol
                        (stdio / JSON-RPC)
                              │
                    ┌───────────────────┐
                    │    Ori MCP Server  │
                    │                   │
                    │  instructions     │   identity auto-injected
                    │  resources  (5)   │   ori:// endpoints
                    │  tools    (16)    │   full memory operations
                    └─────────┬─────────┘
                              │
            ┌─────────────────┼─────────────────┐
            │                 │                 │
      ┌───────────┐    ┌───────────┐    ┌───────────┐
      │ Knowledge │    │ Identity  │    │Operations │
      │   Graph   │    │  Layer    │    │  Layer    │
      │           │    │           │    │           │
      │  notes/   │    │  self/    │    │  ops/     │
      │  inbox/   │    │  identity │    │  daily    │
      │  templates│    │  goals    │    │  reminders│
      └─────┬─────┘    │  method.  │    │  sessions │
            │          └───────────┘    └───────────┘
      ┌─────┴──────┐
      │            │
   Wiki-link   Embedding        ┌──────────────────────┐
    Graph       Index            │ Retrieval Intelligence│
   (in-mem)    (SQLite)          │                      │
      │            │             │  Q-values  (note_q)  │
   PageRank    Semantic          │  Co-occur  (edges)   │
   Spreading   BM25              │  Stage Q   (LinUCB)  │
   Activation  4-Signal          │  Dampening (3 stages)│
   Communities Fusion            │  Explore   (PPR+RMH) │
                                 └──────────────────────┘

---

MCP 工具

工具	功能
ori_wake	会话启动：提供有界简报，并在新建知识库时进行引导
ori_update	写入身份、目标、方法论、每日记录或提醒
ori_update_decision	记录用户对更新通知的答复
ori_whats_new	查看已安装版本或任意版本的发行说明
memory_sql	对索引执行只读 SQL 查询——适用于排名工具无法表达的查询
ori_health	完整诊断
ori_add	捕获到收件箱
ori_promote	通过分类、关联和区域分配进行提升
ori_validate	模式验证
ori_query_ranked	完整检索，包含 Q 值重排、共现 PPR 和阶段元学习
ori_query_similar	语义搜索（仅向量，更快）
ori_warmth	检查关联温度场
ori_explore	递归图遍历——PPR、子问题分解和收敛检测
ori_prune	激活拓扑分析和归档候选项
ori_index_build	构建／更新嵌入索引并引导生成共现边

有 5 个工具已被移除，改由 memory_sql 取代；它可通过一条语句回答这些问题，速度快 20–46 倍，因为它读取索引，而不是从磁盘重新遍历知识库：

之前	现在
ori_status	SELECT COUNT(*) FROM v_note
ori_query orphans	SELECT title FROM v_note WHERE inbound = 0
ori_query dangling	SELECT * FROM v_dangling
ori_query backlinks	SELECT src_title FROM v_link WHERE dst = '…'
ori_query cross-project	SELECT n.title FROM v_note n JOIN note_project p ON p.note_id = n.id GROUP BY n.id HAVING COUNT(DISTINCT p.project) > 1
ori_query_important	SELECT title, pagerank FROM v_note ORDER BY pagerank DESC
ori_query_fading	ori_prune，其自身说明已将此功能交由该工具处理

三个导航式探索工具（explore_start / _expand / _conclude）在连续 6 个月没有任何已记录会话后，从 MCP 中移除。它们仍可通过 ori explore-start、ori explore-expand 和 ori explore-conclude 使用。

---

命令行

# Vault management
ori init [dir]                    # Scaffold a new vault
ori status                        # Vault overview
ori health                        # Full diagnostics
ori whats-new [version]           # Release notes

# Note lifecycle
ori add <title> [--type <type>]   # Capture to inbox
ori promote [note] [--all]        # Promote to knowledge graph
ori validate <path>               # Schema validation
ori archive [--dry-run]           # Archive stale notes
ori prune [--apply] [--verbose]   # Topology analysis + archive candidates

# Retrieval
ori explore <query>               # Recursive graph traversal (RMH)
ori query ranked <query>          # Full intelligent retrieval
ori query similar <query>         # Semantic search
ori query important               # PageRank ranking
ori query fading                  # Vitality detection
ori query orphans                 # Notes with no incoming links
ori query dangling                # Broken wiki-links
ori query backlinks <note>        # What links to this note
ori query cross-project           # Multi-project notes

# Infrastructure
ori index build [--force]         # Rebuild everything derived from the vault
ori index status                  # Index statistics
ori graph metrics                 # PageRank, centrality
ori graph communities             # Louvain clustering
ori serve --mcp [--vault <path>]                                # Run MCP server
ori bridge claude-code [--scope <s>] [--activation <a>] [--vault <p>]  # Claude Code (hooks + MCP + instructions)
ori bridge hermes [--scope <s>] [--activation <a>] [--vault <p>]       # Hermes Agent (plugin + MCP + instructions)
ori bridge opencode [--scope <s>] [--activation <a>] [--vault <p>]     # OpenCode (plugin + MCP + AGENTS.md)
ori bridge cursor [--scope <s>] [--vault <p>]                          # Cursor (MCP config)
ori bridge codex [--scope <s>] [--vault <p>]                           # Codex (TOML config)
ori bridge generic [--scope <s>] [--vault <p>] [--json]                # Any MCP client (prints config)
ori bridge status [--json]                                             # Inspect all bridge installs
ori bridge <target> --uninstall                                        # Remove Ori config for a target

接受路径的命令会将相对文件路径视为相对于知识库的路径。绝对路径仍可照常使用。

何时重建

.ori/ 中存放着两种不同的内容，只有其中一种可以丢弃。

派生数据 — 按需从 Markdown 重建：

存储内容	维护方式	何时需要运行 ori index build
派生索引（note、edge、note_term、图指标缓存）	每次查询时自动维护——每个文件执行一次 stat，仅重新解析有更改的文件	编辑时从不需要；如果查询警告称其“仅覆盖 N/M 条笔记”，则使用 --force
嵌入（语义向量）	写入时由 ori add 维护；仅当表不存在或为空时，查询才会维护	笔记是由 ori add 以外的方式写入的（编辑器、同步客户端、脚本）——它会立即支持关键词和链接搜索，但在生成嵌入前无法按含义搜索
共现引导数据	仅由 ori index build 维护	链接结构发生大量变化，且希望第 0 天的边能反映这些变化

累积数据 — 不会在其他地方保存，重建会将其销毁：

retrieval_log、note_q、q_history、q_history_genuine、stage_q、 stage_log、boosts、note_access、memory_events，以及 co_occurrence 中的 retrieval 行。

在一个包含 1,548 条笔记的知识库中测得：rm -rf .ori/ && ori index build 会清空这些表中的八个——六个月、跨 564 个会话的检索历史，1,427 个已学习的 Q 值，以及决定哪些排序阶段会运行的八个活跃 LinUCB 臂。其中两个表 q_history_genuine 和 memory_events 完全没有任何生产代码会创建，因此也无法通过任何方式重建。

所以，删除前请先导出：

ori index export-learned          # -> ops/ori-learned.ndjson
rm -rf .ori/
ori index build
ori index import-learned

bench/learned-roundtrip.mjs 已验证该往返过程在真实知识库上不会造成数据丢失。它会比较行数，以及基于 Q 值本身计算的摘要，因为行数匹配但值发生漂移的测试通过毫无意义。导出格式为 NDJSON，顺序确定；56,850 行约占 23 MB，而二进制文件有 243 MB——足够小，也足够便于比较差异，可以提交到版本库；二进制文件则不行。

实用规则：尽管编辑和查询；从 Ori 外部批量添加笔记后运行 ori index build，如果查询报告无法覆盖整个知识库，则运行 ori index build --force。 --force 会完整重新解析，但保留累积状态；只有删除文件才会丢失这些状态。

本 README 的早期版本曾称 .ori/ 下的所有内容都是派生数据，可以丢弃。这是错误的，照此操作会损失六个月的学习成果。

---

知识库结构

vault/
├── .ori                       # Vault marker
├── ori.config.yaml            # Configuration
├── notes/                     # Knowledge graph (flat, no subfolders)
│   └── index.md               # Hub entry point
├── inbox/                     # Capture buffer
├── templates/                 # Note and map schemas
├── self/                      # Agent identity
│   ├── identity.md            # Name, personality, values
│   ├── goals.md               # Active threads, priorities
│   ├── methodology.md         # Processing principles
│   └── memory/                # Agent's accumulated insights
└── ops/                       # Operational state
    ├── daily.md               # Today's completed and pending
    ├── reminders.md           # Time-bound commitments
    └── sessions/              # Session logs

每个文件都是纯 Markdown。可在任何文本编辑器、Obsidian 或文件浏览器中打开。git log 就是你的审计记录。

---

部署

本地。 全局安装，运行 ori init，连接 MCP 客户端。完成。

VPS / 无头环境。 在服务端安装。运行 ori serve --mcp --vault /path/to/vault。记忆会保存在文件系统中。使用 git push 备份。

远程终端。 Hermes Agent 支持 Docker、SSH、Modal 和 Daytona 后端。如果你的 Agent 在远程终端中运行，必须在该环境内安装 ori 并将其加入 PATH，且知识库必须存放在持久化存储中（不能使用临时存储）。对于 Modal 这类会休眠环境的无服务器后端，请将知识库挂载到持久卷。

多知识库。 为不同的 Agent 使用彼此独立的 Ori 实例。每个知识库都是独立的：拥有自己的身份、知识图谱和运行状态。

可编写脚本。 CLI 会返回结构化 JSON。可用于 cron 任务、Webhook 处理程序或编排循环。

安装模式

Ori 将安装分为三个概念：

• scope：global 会在整台机器上使用同一个 vault，project 则保留在单个仓库／工作区内
• activation：适配器支持时，auto 会在会话开始时运行 ori_wake；manual 会保留工具可用，但不会自动进行定向
• vault：显式指定的 --vault 优先；否则 Ori 会根据安装范围解析

优先级规则：

• 项目级安装优先于全局安装
• 显式指定的 --vault 优先于推断出的 vault
• 项目级激活设置优先于全局激活设置

桥接生命周期：

• 重新运行相同的 ori bridge ... 命令，即可就地更新 vault 路径或激活设置
• 使用 --uninstall 从支持的适配器中移除 Ori 管理的配置
• 对于通用安装，Ori 会提供手动卸载说明，因为 Ori 不管理该客户端的配置界面

Claude Code、Hermes Agent 和 OpenCode 是完全自动化的适配器，支持生命周期钩子。Claude Code 使用钩子脚本；Hermes 使用安装在 ~/.hermes/plugins/ori/ 的原生 Python 插件；OpenCode 使用位于 .opencode/plugins/lifecycle.js 的 JavaScript 插件。三者都会在会话开始时自动进行定向（通过首次运行检测），并在会话空闲时捕获见解。Cursor 和 Codex 支持原生 MCP 配置安装。Codex 会写入 ~/.codex/config.toml，并使用单一的全局配置界面；其中的“project”范围表示类似项目的运行时 vault 发现机制，而非单独的项目配置文件。其他支持 MCP 的客户端现在可以使用 ori bridge generic，并将生成的配置接入自己的客户端配置界面。

---

配置

ori.config.yaml 控制所有可调参数。在运行 ori init 时会生成包含合理默认值的配置文件。

部分	控制内容
vitality	衰减参数、代谢速率、区域阈值、桥接加成
activation	扩散激活：阻尼、最大跳数、最小加成
retrieval	信号权重、探索预算、RRF k
engine	嵌入模型、数据库路径
warmth	意外度阈值、PPR 参数、图权重
promote	自动提升、项目路由
llm	可选：Anthropic、兼容 OpenAI 的模型或本地模型

LLM 集成是可选的。所有操作仅使用启发式方法也能确定性地运行。配置后，LLM 可以改进分类和链接建议。

---

为什么主权很重要

大多数记忆系统会将 Agent 的知识存储在你无法控制的基础设施中：专有数据库、云服务或供应商专属格式。

Ori 将记忆存储为你拥有的文件。vault 可移植。你可以将它迁移到新机器、推送到 git 远程仓库，或在文本编辑器中打开。只需更改一行配置，就能切换 MCP 客户端。由于记忆从未被锁定在某个平台上，因此无论平台如何变化，它都能留存。

这不是意识形态，而是架构设计。可移植的记忆才能组合使用。

---

开发

git clone https://github.com/aayoawoyemi/Ori-Mnemos.git
cd Ori-Mnemos
npm install
npm run build
npm link
ori --version

npm test              # 860+ tests
npm run lint          # Type check
npm run dev           # Watch mode

提交 PR 前，请参阅 CONTRIBUTING.md。

感谢 @maichler 和其他 Ori 社区成员提交的 PR 和补充内容。

---

许可证

Apache-2.0

---

记忆即主权。Ori 赋予你的 Agent 一颗心智。