Mnemosyne

Mnemosyne

下一个 Agent 将更加明智。

Mnemosyne 是一款本地优先的 AI Agent 长期记忆工具：只需一个 SQLite 文件，就能将 Agent 学到的内容及其来源证据一并保存，并通过 TypeScript、MCP、命令行或 HTTP 提供给任何主机。 当某个来源得到更正时，记录为依赖该来源的记忆也会一并退役，因此下一个 Agent 会依据当前记录仍然支持的证据开始工作，而不是重复过时的经验。本地引擎无需模型 API 密钥、数据库服务或 Docker。

• 每条记忆都有证据。 每条记录都会保留其来源和信任级别；更正后，被取代的版本仍可供检查。
• 更正会传递给依赖项。 需求更正后，记录为依赖该需求的流程和技能都会退役；3.0 还可以找出无人声明的依赖项并提出建议，供人审核。
• 随时间审计。 过去的信念可以精确重现。给定检索失败时本应返回的记录，bisect 会找出将它们挤出的记录。在 3.0 预发布版中，整合以结果为门槛，且可以撤销。
• 适用于任何主机。 为 Claude Code、Cursor 和 Codex 提供 MCP；另有 TypeScript SDK、命令行，以及配有 Python 客户端和实时检查器的已认证 HTTP 接口。

稳定版：2.0.0（npm install mnemosy-ai） · 最新预发布版：3.0.0-rc.4，突破性版本（npm install mnemosy-ai@next） · MIT · Node.js ≥22.16

网站 · 快速入门 · 文档 · 示例 · 迁移 · 测量结果 · 信任证据 · 声明与证据 · 版本发布 · npm · 贡献指南 · 问题反馈

说明

这是哪个 Mnemosyne？ 此仓库是通过 npm 以 mnemosy-ai 发布的 TypeScript 软件包，网站为 mnemosy.ai。它与 mnemosyne-oss/mnemosyne 是两个独立项目；后者是通过 PyPI 以 mnemosyne-memory 发布的 Python 记忆库。这两个项目只是名称相同，代码和维护者均不相同。请在该项目自己的仓库中提交相关问题。

试用

首次运行 npx 时会下载软件包；之后，3.0.0-rc.4 演示可在合成语料上离线运行，无需 API 密钥或模型，并会在运行时衡量每项声明：

npx -y -p mnemosy-ai@next mnemosy demo

上方录制的是一次未经剪辑的运行（assets/demo.tape 可通过 vhs 重新生成）。以下是五个片段中每个片段的最后一行，与 2026 年 10 月 28 日录制的运行相符（site/demo-five.json；耗时因机器而异；此处省略每行之后打印的通过条）：

PROOF  replay determinism: 1000/1000 identical, 24000/24000 as-of answers = ground truth   [PASS]
PROOF  downstream repair: undeclared invalidated 3/3, accepted edges true 3/3, stale after correction 0 (11 probes)   [PASS]
PROOF  blame precision / time-to-locate: precision 1.00, 0.40 s, 2000 records   [PASS]
PROOF  poisoning suite v1, live: 227 cases, 0 escapes, 0 false quarantines   [PASS]
PROOF  consolidation receipts: kept 1 (delta +2), rolled back 2 (regression, invariant violated), rollback identical hash true, chain verified 4 receipts   [PASS]

5/5 moments proved.

每个片段能证明什么，以及不能证明什么。接下来，将记忆交给 Claude Code（其他客户端请参阅：安装并连接 Agent）：

claude mcp add mnemosyne -- npx -y -p mnemosy-ai@next mnemosy mcp --db ./.mnemosyne/memory.sqlite --workspace my-project --agent assistant

要使用稳定版，请将 mnemosy-ai@next 替换为 [email protected]；在 2.0.0 中，mnemosy demo 会运行早期的单场景演示。

目录： 3.0：突破性版本 · 安装并连接 Agent · 实测结果 · 选择引擎 · 运行演示 · 代码中的修正 · 调整密集索引 · 你可以构建什么 · 入口点 · 迁移 · 限制 · 运行边界 · 与我们一起构建

3.0 新增内容：突破性版本（npm next 上的预发布版）

3.0 是一个突破性版本。回放和 bisect 在 2.0.0 中就已存在。3.0 新增四项功能：发现未声明的依赖项，并提出建议供审核，让修正一经接受便能传递到这些依赖项；通过可复现攻击套件验证的投毒拦截机制；由结果门控、可撤销且带有签名回执的整合；以及可选的精度控制。bisect 还新增了混合检索路径：从 3.0.0-rc.4 起，mnemosy bisect CLI 会重新执行存储自身的路径（--retrieval auto|lexical|hybrid，默认值为 auto；当存储中包含捆绑模型的向量时会选择混合检索；若使用 hnsw 索引则会拒绝运行）。bisect 不是公开的软件包导出项，因此从 npm 使用时，CLI 是入口。这些功能均在下文记录并经过测试，每项公开声明及其证据都列在声明与证据中。3.0.0-rc.4 是 npm next 频道上的当前候选发布版：运行 npm install mnemosy-ai@next 会安装该版本，而 npm install mnemosy-ai 仍会安装稳定版 2.0.0。下文所有数字均在 3.0.0-rc.2 上测得，运行时离线、无需 API 密钥、付费模型或 LLM 评审。每项结果都可通过基准测试与可信证据中的命令复现，其中也列出了未作出的声明。

测量项	结果	协议
PrecisionMemBench	70/77 单轮，11/12 会话轮次（rc.1：未过滤为 22/77，使用调优后的封装过滤器为 48/77，会话为 6/12）	面向这些控制措施设计的公开 35 条信念测试样例，严格遵循协议，检索模式，无封装侧过滤器，无 LLM 裁判 · 协议
Poisoning suite v1，启用整合	0/167 次逃逸，0/60 次误隔离（未启用门控时逃逸 85/167 次）	227 个合成案例，词法路径，294 次门控决策 · 协议
Dependency suite v1	召回率 96.05 %，精确率 98.06 %，使用前提条件保护时有 0 个过时流程（仅靠推断：7/248 个过时流程；保护机制误拦率为 92.78 %）	合成语料库，种子 20261028，120 次纠正，全接受评估审核器 · 协议
重放确定性	1000/1000 个状态完全相同，24,000/24,000 个时点答案	同一存储的两个读取器，在 1000 个带种子的时间切点上运行；答案根据计划中的真实情况进行验证 · 协议
二分查找	在 2,000 条记录上的精确率为 1.00，在 2026-10-28 的记录运行中耗时 0.40 s（site/demo-five.json；因机器而异；限时 60 s）	在合成存储中插入一条带种子的错误记录；预期记录已知，并通过重新运行召回（不含问题记录）确认归因 · 协议

默认检索路径的召回率没有变化：LoCoMo 和 LongMemEval-S 的召回率在前后完全相同（回归检查）。召回延迟仅在一台高负载机器上测量，使用的临时测试工具未提交，因此无法从此仓库复现这些数据；已知限制（包括非默认 overlap 评分器的速度下降）列于更新日志。

• 可启用的精准控制。 新增的可选控制包括名称门控和带保护的单条编辑模糊匹配。空答案是原生的弃答，账本会记录原因。启用这些控制后，内核在 PrecisionMemBench 上单轮用例得分为 70/77，会话轮次得分为 11/12（使用 rc.1 的过滤配置时，会话得分为 6/12）。该次运行严格遵循协议，处于检索模式，不使用 LLM 评审、包装器侧过滤器或包装器 kinds 谓词；词法路径和混合路径的得分相同。第 12 个会话轮次需要一种内核并未获知的开放问题类型策略。

  • 作为对比，内核在未过滤时得分为 22/77，使用 rc.1 中针对测试夹具调优的包装器过滤器时得分为 48/77。
  • 基准测试夹具是公开的，这些控制也是针对它设计的，因此这并非留出集估算。
  • 剩余的 7 个未通过项与我们的基于元数据的配置有关；单轮协议不会发送明确的生命周期字段。
  • 默认检索路径保持不变：LoCoMo 和 LongMemEval-S 的召回率在变更前后完全相同。

• 必须证明自身价值的整合。 整合过程会生成签名差异，并根据 Agent 自身记录的结果进行重放。只有在该重放集上的总体词法覆盖率没有下降且没有违反任何不变量时，才会保留整合结果。若保留后的内容未发生变化，可通过一条命令撤销；只有在整合后没有写入任何内容时，可见记录状态哈希才会恢复为完全相同的值。标准 MCP 设置中默认关闭此门控：宿主通过在账本中记录查询文本和验证器结果，从 SDK 启用它（方法）。启用整合后，投毒测试套件 v1 的运行（227 个合成用例，可复现）结果为 零漏网：167 次攻击中有 0 次漏网，60 个良性控制中有 0 个被误隔离，共进行了 294 次门控判定。未启用门控的对照组中，167 次攻击有 85 次通过。整合门控 · 签名与回执

• 让修正触达无人关联的内容。 系统会根据成功的共同使用推断依赖项，并提出建议供审核。接受后，依赖项会通过 correct() 声明，运行时技能也可以链接到其前提。测量基于一个合成种子语料库（依赖套件 v1，种子 20261028，共 120 条修正）：

  • 失效召回率为 96.05 %；
  • 已接受边的精确率为 98.06 %；
  • 0 个过时流程通过前提门控运行。这个零值来自门控本身：凡是与已变更前提共同使用过的内容，一律暂缓处理。仅靠推断时，248 次检查中有 7 次仍会过时；门控的误暂缓率为 92.78 %。

  推断出的依赖项

• 能自我衡量的演示。 mnemosy demo 会离线地在合成语料库上、通过零模型词法路径，演示以下五个时刻：

  1. 精确重放过去的信念；
  2. 修正触达无人关联的依赖项；
  3. bisect 找到将已知正确答案挤出结果集的种子记录；
  4. 捕获投毒企图，并实时运行测试套件；
  5. 保留一次整合、回滚另一次整合，并撤销已保留的整合。

  每个时刻都会输出一条根据本次运行测得的 PROOF 行。每个时刻证明了什么

npx -y -p mnemosy-ai@next mnemosy demo             # five moments, offline, each PROOF line measured live
npx -y -p mnemosy-ai@next mnemosy demo --classic   # the previous single-scenario demo

在源码检出目录中，运行 npm run build，然后运行 node dist/cli/index.js demo。

3.0 是一次破坏性版本更新：旧版向量引擎迁移至 mnemosy-ai-legacy，目前尚未发布到 npm；请从检出目录构建，或继续使用 mnemosy-ai@2（3.0 迁移指南）。发行说明见更新日志。

安装并连接 Agent

选择一种方式：

npm install mnemosy-ai                   # stable: latest = 2.0.0; pin [email protected] to reproduce
npm install mnemosy-ai@next              # or the pre-release: next = 3.0.0-rc.4; pin [email protected] to reproduce

然后，在该项目中，npx --no-install mnemosy demo 会离线运行已安装版本的演示（无需 API 密钥、服务或 Docker）；如果没有安装任何版本，--no-install 会让 npx 失败，而不是获取其他软件包。如果不安装，npx -y -p [email protected] mnemosy demo 会下载并运行指定版本。

将记忆提供给 MCP 客户端。下方条目通过 mnemosy-ai@next 运行 3.0.0-rc.4 预发布版（Hermes 条目固定使用 [email protected]）；对于稳定版，请将其替换为 [email protected]；要固定使用预发布版，则写为 [email protected]。两个版本提供相同的 MCP 工具。mnemosy mcp 需要 --db、--workspace 和 --agent。数据库文件（权限模式为 0600）及其父目录（权限模式为 0700）会在首次使用时创建；请将 .mnemosyne/ 添加到项目的 .gitignore 中。相对路径相对于客户端启动服务的目录解析；如果客户端会在其他位置启动服务，请使用绝对路径。PATH 中必须包含 Node.js >= 22.16 和 npx。

每个宿主都标记为 已测试（我们运行了所示命令，并使用了注明的版本）或 有文档记录（根据宿主的文档编写；我们未运行这些命令）。

Claude Code

插件。 此仓库是 Claude Code 插件市场（mnemosy-ai，文件 .claude-plugin/marketplace.json），其中包含一个插件 mnemosyne（integrations/claude-code）：

claude plugin marketplace add 28naem-del/mnemosyne      # in a session: /plugin marketplace add 28naem-del/mnemosyne
claude plugin install mnemosyne@mnemosy-ai             # add --scope project to share it through .claude/settings.json

使用 Claude Code 2.1.301 已测试：通过上述命令，从这些文件的本地检出副本和 GitHub 执行（针对 main 运行）：claude plugin validate 通过，claude mcp list 显示 plugin:mnemosyne:mnemosyne 已连接，且会话中列出 16 个工具。该插件会启动 npx -y -p mnemosy-ai@next mnemosy mcp --db ${CLAUDE_PROJECT_DIR}/.mnemosyne/memory.sqlite --workspace default --agent claude-code，因此每个项目都有自己的数据库。在 Claude Code 中，其工具名称为 mcp__plugin_mnemosyne_mnemosyne__memory_*；权限规则必须使用这种形式。

不使用插件。 Claude Code 会读取项目根目录中的 .mcp.json：

{
  "mcpServers": {
    "mnemosyne": {
      "command": "npx",
      "args": [
        "-y", "-p", "mnemosy-ai@next", "mnemosy", "mcp",
        "--db", "./.mnemosyne/memory.sqlite",
        "--workspace", "my-project", "--agent", "assistant"
      ]
    }
  }
}

或者从命令行注册相同的服务：

claude mcp add mnemosyne -- npx -y -p mnemosy-ai@next mnemosy mcp --db ./.mnemosyne/memory.sqlite --workspace my-project --agent assistant

使用 Claude Code 2.1.301 已测试：运行 claude mcp add 后，claude mcp list 会显示服务已连接；对于 .mcp.json，则需要先信任项目并批准其服务。

Cursor

有文档记录。 我们无法使用 Cursor，因此下面两种配置方式都未运行。

按钮会打开 Cursor 的安装页面；直接链接为 cursor://anysphere.cursor-deeplink/mcp/install?name=mnemosyne&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIi1wIiwibW5lbW9zeS1haUBuZXh0IiwibW5lbW9zeSIsIm1jcCIsIi0tZGIiLCIke3VzZXJIb21lfS8ubW5lbW9zeW5lL21lbW9yeS5zcWxpdGUiLCItLXdvcmtzcGFjZSIsImRlZmF1bHQiLCItLWFnZW50IiwiY3Vyc29yIl19。两种方式都会添加一个全局服务，其数据库位于 ${userHome}/.mnemosyne/memory.sqlite，供所有 Cursor 项目共用。若要让每个项目使用独立数据库，请改为将以下内容放入项目的 .cursor/mcp.json 中：

{
  "mcpServers": {
    "mnemosyne": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y", "-p", "mnemosy-ai@next", "mnemosy", "mcp",
        "--db", "${workspaceFolder}/.mnemosyne/memory.sqlite",
        "--workspace", "default", "--agent", "cursor"
      ]
    }
  }
}

Codex

Codex 在 ~/.codex/config.toml 中保存 MCP 服务。使用绝对数据库路径注册服务：

codex mcp add mnemosyne -- npx -y -p mnemosy-ai@next mnemosy mcp --db /absolute/path/project/.mnemosyne/memory.sqlite --workspace my-project --agent assistant

该命令写入下方配置表，但不包含最后一行。Codex 默认等待服务启动 10 s，而首次启动 npx 会下载软件包，因此请手动添加 startup_timeout_sec = 60（或自行编写完整配置表）：

[mcp_servers.mnemosyne]
command = "npx"
args = ["-y", "-p", "mnemosy-ai@next", "mnemosy", "mcp", "--db", "/absolute/path/project/.mnemosyne/memory.sqlite", "--workspace", "my-project", "--agent", "assistant"]
startup_timeout_sec = 60

已测试，仅验证配置，使用 codex-cli 0.153.4：codex mcp add 写入了配置表，codex mcp list 和 codex mcp get 读取到已启用的配置，包括 startup_timeout_sec。尚未在 Codex 会话中运行该服务。

Hermes Agent

有文档说明，但未经测试：我们的 CI 或开发环境中没有 Hermes。Hermes 从 ~/.hermes/config.yaml 读取 MCP 服务：

# ~/.hermes/config.yaml
mcp_servers:
  mnemosy:                       # not "mnemosyne": avoids confusion with the mnemosyne-oss provider
    command: "npx"
    args: ["-y", "-p", "[email protected]", "mnemosy", "mcp",
           "--db", "/absolute/path/.mnemosyne/memory.sqlite",
           "--workspace", "hermes", "--agent", "hermes"]
    connect_timeout: 120         # default 60 s; the first npx run downloads the package
    # trust: untrusted           # optional: ask before every write tool (read tools carry readOnlyHint)

integrations/hermes 包含相同服务的 Hermes 便携插件（mnemosy-ai，包含一个 MCP 服务和一个技能）。该插件未列入 Hermes 插件目录。

所有宿主

首次启动 npx 会下载软件包；如果客户端在首次启动时放弃等待，请先在项目中安装该软件包。

该服务提供 16 个 memory_* 工具（memory_store、memory_recall、memory_context、memory_correct、memory_checkpoint、memory_resume、memory_observe、memory_skill，……）；只有在使用 --allow-destructive 启动服务时，才会添加 memory_forget。添加 --read-only 可省略所有修改类工具。模型无法通过 MCP 切换工作区、提高自身信任级别或报告自身的技能试验。MCP 工具不包含整合、bisect 或结果记录功能，因此在此配置下，3.0 结果门控保持关闭（通过 SDK 启用）。本仓库中供 Agent 阅读的摘要见 llms.txt 和 AGENTS.md；完整的 MCP 协议约定见通过 MCP 连接。

测得：LongMemEval-S 得分 409/500，并公开了未答对的问题

项目	结果	测量方式
答案准确率，LongMemEval-S，全部 500 个问题	答对 409 / 500（81.8%），Wilson 95% 置信区间为 78.2–84.9；完全匹配率为 7.6%	Mnemosyne 重排检索，将排名前 20 的命中项打包至 16 KB，由 claude-sonnet-4.6 阅读，并由 claude-haiku-4.5 评判。提示词和预算在 100 个问题上选定；其余 400 个问题的得分为 82.3%。
重排器带来的提升，LoCoMo，1,531 个已标注问题	MRR@10 从 0.461 升至 0.624，提升 0.163（配对自助法 95% 置信区间为 0.146–0.181；599 次胜出，133 次落后）	在发布版本上，对同一混合候选集分别使用和不使用随附的交叉编码器进行测量。
与 Mem0 OSS 对比，使用相同语料库、分块、K、打包预算、评分器，运行于单个进程	LoCoMo recall@10：使用 Mnemosyne 重排器时为 73.57，对比 Mem0 OSS 的 63.72；LongMemEval-S recall@20 持平，均为 96.67。不使用重排器的快速模式在 LoCoMo 上各个 K 值均比 Mem0 低不到 1 个百分点；Mem0 的 LongMemEval-S MRR 更高	COMPARISON.md，所有落后项都列在相同的表格中

这些数字并不代表什么。 81.8% 并非相较此前 71.2% 的配对提升：此前的基准使用了不同的 250 题样本、提示词和预算，因此提升归功于整套改动。阅读器具有非确定性；重新运行同一配置会让得分上下波动约 1 个百分点。检索数字衡量的是覆盖率，而非答案。2.0.0 的两个 Tier 1 目标未达成，但仍随版本发布并披露：100 万条记录下的召回延迟为 p95 139–223 ms，高于 50 ms 的目标（可选择启用 indexMode: 'hnsw'，参见调整密集索引）；上下文重排器的全证据命中率为 71.98%，低于 72.80% 的门槛 0.82 个百分点（1,531 个问题中少 13 个）；尝试过的最佳变体仍差 4 个，未合并。命令和原始输出见 reports/t1-targets/evidence/；答案准确率和门槛结果及其提交记录也已在变更日志中重述；Mem0 和重排器的检索对比表见 COMPARISON.md。

选择你的引擎

2.0.0 随附两种引擎；从 3.0.0-rc.2 起，mnemosy-ai 随附本地引擎，向量引擎移至 mnemosy-ai-legacy。 请选择适合你应用的存储和运行时：

引擎	最适用场景	SDK 入口	指南
向量引擎	使用现有服务支持型记忆架构的应用。需要配置外部服务。	从 mnemosy-ai 2.x 导入 createMnemosyne；从 3.0 起，该功能位于单独的 mnemosy-ai-legacy 包中	可运行示例 · 版本 2 变更 · 3.0 拆分
本地引擎	自包含的 SQLite 记忆存储，具备证据、修正和 Agent 生命周期工具。	从 mnemosy-ai/local 导入 createLocalMemory	本地 API · Agent 生命周期

MemoryAgent 适配器使用本地引擎的运行时。这两种引擎使用不同的架构，不会自动迁移或同步数据。如需逐步过渡，请通过只读迁移桥接显式连接现有存储；此操作不会更改该存储。

引擎选择与版本选择彼此独立：mnemosy-ai@latest 是 2.0.0，包含两种引擎；1.x 系列仍可通过 mnemosy-ai@1 安装。从 1.x 升级会带来破坏性变更：升级现有向量引擎应用前，请阅读迁移说明。从 3.0.0-rc.2（npm next）起，向量引擎已从 mnemosy-ai 移至 mnemosy-ai-legacy 包；该包尚未发布到 npm。请参阅 3.0 迁移说明。

从可运行的演示开始

在项目中安装此软件包。推荐使用 Node 24；本地记忆引擎无需模型 API 密钥、数据库服务器或 Docker。

npm install mnemosy-ai                   # stable 2.0.0; or mnemosy-ai@next for the 3.0.0-rc.4 pre-release
npx --no-install mnemosy demo            # runs the installed package offline; the install itself needs the network
npx --no-install mnemosy learning-demo

不指定版本的 npm install mnemosy-ai 会使用 latest 频道，该频道截至 2026 年 10 月 27 日对应 2.0.0；为确保部署可复现，请固定为 [email protected]。npm install mnemosy-ai@next 会安装预发布版 3.0.0-rc.4；要复现该版本，请固定为 [email protected]。如果你要从 1.x 系列升级，请先阅读迁移说明：版本 2 更改了向量检索评分、启动索引和擦除行为，且不会迁移现有数据库。投入生产前，请在自己的工作负载上进行评估。Python 注册表的发布是独立的；可从检出目录安装捆绑的 Python 客户端。

要从源代码构建并运行同一版本（预发布版请使用 --branch v3.0.0-rc.4）：

git clone --branch v2.0.0 --depth 1 https://github.com/28naem-del/mnemosyne.git
cd mnemosyne
npm ci --ignore-scripts
npm run build
npm run demo
npm run demo:learning

在 2.0.0 中，第一个演示使用临时数据库展示交接、更正、私有范围和遗忘。从 3.0.0-rc.2 起，mnemosy demo 是五幕演示，而 2.0.0 演示可通过 mnemosy demo --classic 运行。学习演示涵盖捕获、脚本化观察任务、技能试用、显式共享和由更正触发的退役。两者都会运行真实的本地 API，使用确定性固件，且不会调用模型。选择下一个示例。

要进行完整的贡献者验证，请运行 npm run check、npm run check:docs 和 npm run check:public。2.0.0 是从 2.0.0-rc.10 候选版晋升为稳定版的版本，没有源代码变更（变更日志中注明了一项依赖安全补丁：zod 4.6.2 → 4.6.7）；它在 RC9 的打包基础上包含 Tier 1 检索工作（混合检索默认启用、交叉编码器重排序、可选密集索引和时间路由）。已记录的评估报告仍是对其所注明版本和条件的历史测量结果。

要在另一个项目中使用已构建的检出目录，请在该项目中运行 npm install /absolute/path/to/mnemosyne。请确保检出目录及其 dist 目录始终可用。较早的 RC8 GitHub 发布版和带校验和的下载文件保持不变。

更正应改变下一个 Agent 的行为

import { createLocalMemory } from 'mnemosy-ai/local';

const memory = createLocalMemory({
  path: './agent-memory.sqlite',
  workspaceId: 'catalogue',
  agentId: 'designer',
});

const brief = memory.store({
  text: 'Product images must be 1200 by 900 pixels.',
  kind: 'fact',
  key: 'catalogue.image-size',
  source: { uri: 'brief://catalogue/v1' },
  trust: 'observed',
  visibility: 'workspace',
});

const procedure = memory.store({
  text: 'Export catalogue product images at 1200 by 900 pixels.',
  kind: 'procedure',
  source: { uri: 'run://designer/export' },
  trust: 'observed',
  dependencies: [brief.id],
  visibility: 'workspace',
});

memory.correct(brief.id, {
  text: 'Product images must be 1600 by 1200 pixels.',
  source: { uri: 'brief://catalogue/v2' },
  reason: 'The delivery specification changed.',
});

console.log(memory.get(procedure.id)?.status); // invalidated
const context = memory.compile({
  query: 'catalogue product images',
  maxTokens: 2048,
});
console.log(context.text); // Send eligible context to your responder.
// Inspect context.citations and context.uncertainty alongside the text.
memory.close();

旧流程仍可供查看，但不再具备作为当前指导的资格。依赖项由控制器声明。在 3.0 中，依赖项模块还可以根据成功的共同使用情况提出未声明的依赖项，由审查者逐项接受或拒绝。observed 表示宿主记录了来源；这并不代表该来源真实无误。默认上下文计数器会保守地计算 UTF-8 字节数，而非使用模型的分词器。上下文约定。

调整稠密索引

无需进行任何这些调整，Recall 也能正常工作。这三个选项适用于规模足够大、默认设置不再合适的存储，且都需要主动启用。

const memory = createLocalMemory({
  path: './agent-memory.sqlite',
  workspaceId: 'catalogue',
  agentId: 'designer',

  indexMode: 'hnsw',            // 'exact' | 'auto' (default) | 'sqlite-vec' | 'hnsw'
  sqliteVecPath: '/opt/lib/vec0.dylib',  // explicit extension path; no env-var equivalent
  cacheSize: -65536,            // PRAGMA cache_size: negative = KiB, positive = pages
});

indexMode — 要搜索的稠密索引。默认使用 $MNEMOSYNE_INDEX_MODE，否则为 auto。

mode	作用
exact	为每个已授权向量评分。不需要可选二进制文件或索引文件，也是衡量其他模式的基准。
auto (默认)	扩展加载成功时使用 sqlite-vec，否则使用 exact。仍是精确搜索——vec0 在 C 中为相同的向量评分，而不是在 JS 中评分。
sqlite-vec	与 auto 相同，但扩展不可用时会抛出错误，而不是静默降级。
hnsw	近似且亚线性，适用于向量超过数十万条的存储。这是此处唯一可能会漏掉真实近邻的检索组件，因此绝不会替你选择。它未达到 1M 条记录时 p95 为 50 ms 的目标：实测为 139–223 ms（参见 CHANGELOG）。

显式指定 sqlite-vec 或 hnsw，但无法使用时，会报错而不是降级：这两种模式在后端不可用时都会抛出错误。只有 auto 会降级，而且只会降级为精确搜索，绝不会降级为近似搜索。

任何模式都不会改变记录的评分，也不会改变记录是否可以返回。索引提出的每个候选项，在返回给你之前都会重新验证授权，并根据存储的向量重新评分，因此索引只负责筛选候选项，并非权威来源。

sqliteVecPath — sqlite-vec 可加载扩展的显式文件系统路径，会覆盖捆绑包自身的解析方式。仅当 indexMode 为 auto 或 sqlite-vec 时才会使用。

这里有意不提供等效的环境变量。由环境变量控制的路径会导致机器上打开的每个 LocalMemory 默认都通过 dlopen 加载该变量所指向的内容，即使调用方并未提出要求。加载原生扩展是调用代码在打开时必须作出的决定，因此该选项只存在于构造函数中。

cacheSize — 每次打开时应用的 PRAGMA cache_size，使用 SQLite 自身的单位：正值表示页数，负值表示 KiB 预算。默认值为 -65536（64 MiB）；由于页面大小可能不同，推荐使用负值。必须是非零整数：正值最多为 524,288 页，负值的绝对值最多为 2,097,152（按默认页面大小计算，两者上限均为 2 GiB）。

较大的页面缓存可以减少短名单重新评分和 BM25 倒排列表访问操作系统页面缓存的次数；热路径每次查询都会读取这些内容。当工作集超出 SQLite 默认选择的几 MB 缓存容量时，这一设置就会派上用场。但它确实会占用内存，并且每个打开的连接都会产生这项开销，因此需要显式设置，而不是由系统猜测。

可以构建的功能

能力	行为	开发者指南
带证据的记忆	默认私有的记录、显式共享、修正、冲突、来源历史和依赖项退役。	本地 API
跨 Agent 连续性	结构化检查点保留目标、决策、产物和后续操作；来源变更可使过时的交接内容退役。	Agent 生命周期
自适应上下文	有预算限制的观察、分层摘要和可展开的原始来源字节，并重新验证证据。	上下文
跨词语与语义检索	默认使用限定范围的 BM25；可选在获授权的记录上使用嵌入、混合融合和重排。	本地语义检索
跨时间记忆	分离 asOf 和 knownAt 查询、计划修正以及因果失效历史。	运行时
证据门控技能	候选流程、明确的试用要求，以及证据失败或变更后的退役。	技能与试用
有来源支持的档案	类型化字段会报告受支持的值、未知项或冲突，并重新验证其输入。	档案
静默过时检查	明确的来源策略、上次确认的证据、有界探测，以及与操作绑定的依赖检查。	新鲜度
受控过渡	只读访问你之前的存储、逐步优先使用本地数据、协调以及路由回滚。	渐进式迁移
完整导入与恢复	十一种导出配置、预览、原子应用、防重放保护、受保护的撤销和整库备份（整合签名密钥是需要单独备份的文件）。	导入 · 恢复
由宿主控制的处理	持久化的有界任务、有来源支持的项目模型、结果追踪、实体关系和分阶段变更。	运行时

本地引擎，多种入口

flowchart LR
  Host[Your agent or application] --> Interfaces[TypeScript · MCP · CLI · HTTP / Python]
  Interfaces --> Runtime[Capture · Context · Trials · Action checks]
  Runtime --> Store[(Local SQLite memory)]
  Store --- Evidence[Sources · History · Dependencies · Outcomes]
  Runtime -. explicit configuration .-> Models[Optional model providers]
  Runtime -. read-only adapter .-> Previous[Previous memory system]

宿主负责选择身份、信任声明、提供方和执行预算。构造过程不会启动工作线程或下载模型。MemoryAgent 可在一轮对话前准备上下文，并在之后捕获提供的可见输入／输出；只有宿主启动后台工作时，它才会运行。宿主循环。

本地数据库保存记忆、向量和运行时状态。经明确配置后，可选的本地 CPU 提供方会在独立进程中运行缓存的推理。其依赖项要求、模型身份和许可证记录在本地模型指南中。现有后端集成仍可通过 createMnemosyne 使用（从 3.0 起位于 mnemosy-ai-legacy）；它不会自动与本地引擎同步。版本 1 迁移说明。

通过 MCP 连接

使用 npm 包时，请使用安装并连接 Agent中所示的 npx 入口。从源码检出目录运行时，请改为将客户端指向构建好的 CLI；数据库的父目录会在首次使用时创建。

{
  "command": "node",
  "args": [
    "/absolute/path/mnemosyne/dist/cli/index.js", "mcp",
    "--db", "/absolute/path/data/memory.sqlite",
    "--workspace", "my-project", "--agent", "assistant"
  ]
}

使用 --read-only 可省略变更工具。遗忘操作需要通过 --allow-destructive 显式启用。模型无法选择其他工作区、提升自身信任级别，也无法通过 MCP 报告试用成功。有关经过身份验证的服务、Python 访问和实时检查器，请参阅 HTTP 和 Python。原生提供方工具协议记录在适配器指南中。

要求更有力的技能证据

import { createLocalMemory } from 'mnemosy-ai/local';
import {
  MemoryRuntime,
  RECOMMENDED_SKILL_PROMOTION_POLICY,
} from 'mnemosy-ai/runtime';

const memory = createLocalMemory({
  path: './skills-memory.sqlite', workspaceId: 'my-project', agentId: 'assistant',
});
const runtime = new MemoryRuntime(memory, {
  skillPromotionPolicy: RECOMMENDED_SKILL_PROMOTION_POLICY,
});
// Use runtime to create candidates and record controller trials.
memory.close(); // Close after your host finishes using the runtime.

推荐策略要求候选项在两项不同任务和两个不同验证者身份下均成功通过试验。在存储的要求得到满足之前，候选项不会进入建议上下文；较弱的配置无法降低现有候选项的要求。兼容性默认值仍为一项任务和一个验证者。身份和试验结果均由控制器声明，因此宿主必须提供真实测试和独立证据。试验契约。

在 Agent 持续工作的同时迁移

可选的 mnemosy-ai/bridge 封装了你明确提供的旧版搜索适配器。它会复制已使用的记录并保留稳定来源，比较成对的检索结果，并在观测到的覆盖率达到配置阈值时，依次从影子路由切换到辅助路由，再切换到优先路由。未匹配到的旧版记录仍可使用，路由也可以切回先前的系统。

桥接层会继续查询原存储以进行协调，且绝不会向其中写入或删除数据。进度衡量的是观测到的查询，而不是完整存储迁移或答案质量。宿主凭据、来源选择和最终切换仍由你掌控。桥接契约。

如需完整导出迁移，请从 11 种受支持的配置中选择一种，预览确切的源字节，然后原子性地应用经审核的计划。导入内容默认设为私有且不受信任；同时支持重试识别、来源检查、受保护的撤销和防止重复执行擦除操作。外部嵌入和不受支持的策略语义不会被悄悄转换。完整迁移。

node --experimental-strip-types examples/gradual-migration.ts
node --experimental-strip-types examples/migration.ts
node --experimental-strip-types examples/maintenance.ts

这些示例使用隔离的合成数据，不会连接到你现有的账户或记忆存储。

有实测数据，局限也清晰可见

成对的 LongMemEval S 检索运行包含全部 500 个问题，其中 470 个有标注且可回答的问题具有正向证据指标。两种检索条件都使用 20 个分块和相同的 8,192 字节上下文预算。

完整标注会话覆盖率	早期重叠评分器	当前 BM25 默认配置
上下文打包前	386 / 470（82.13%）	425 / 470（90.43%）
上下文打包后	367 / 470（78.09%）	382 / 470（81.28%）

30 个弃答问题仍计入尝试次数，但不计入正向检索得分。全部 500 个完整历史记录对照均超出上下文预算，并报告为溢出。此次运行采用同日时间戳兼容规则，其中包括 1,475 个晚于所述问题时点的会话。会话命中可能来自该会话的任意分块；这并不能证明包含答案的句子已传递给模型。未调用嵌入、生成或评判器。

这些结果衡量的是相对于早期本地评分器的检索覆盖率。它们不能证明生成答案的准确性，也不能证明优于其他系统。原始报告和指纹 · 复现流程。

与另一种记忆系统对比

针对 Mem0 OSS 的同条件竞品基准测试已发布于 COMPARISON.md——使用相同语料、相同分块、相同 K 值、相同打包预算，在同一个进程中进行评分；Mem0 胜出的结果也与它未胜出的结果一同列在表格中。简而言之：启用重排器后，Mnemosyne 在 LoCoMo 上以 73.57 的 recall@10 超过 Mem0 的 63.72；在 LongMemEval-S 上，两者的 recall@20 持平。未启用重排器的快速模式在 LoCoMo 的每个 K 值上都落后于 Mem0，召回率差距不到 1 个百分点，MRR 也更低；在 LongMemEval-S 上，Mem0 的 MRR 更高。Zep Cloud 于 2026 年 10 月 29 日在另一次同条件测试中进行评估（仅 LoCoMo、免费套餐、情节搜索）；结果及相关披露见 COMPARISON.md，完整报告和原始输出见 reports/matched-run-2026-10-29-zep.md。未测试 Graphiti。这些是没有阅读器和评判器参与的检索覆盖率数据，不代表答案准确率。

单独的证据生命周期诊断用于测试纠正、时间、冲突、失败、擦除和范围行为。它刻意保留了一个失败案例：更改无关字段可能会使一条仍然有效的依赖规则失效。工程评审和发布状态会跟踪这一问题及其他待办事项。

运行边界

工作区和 Agent ID 是受信任的控制器选择器，并非租户身份验证。HTTP 服务提供绑定范围的持有者身份验证；远程 TLS 和企业身份验证需要进行应用部署工作。数据库和纯备份包均以明文存储；--encrypt 备份包则使用口令加密（运维）。遗忘操作会移除涵盖范围内的实时内容，并阻止已知源的重放，但无法擦除旧备份或已发送给模型的提示词。

本地语义搜索会在符合条件的索引语料中进行扫描，并限制保留的候选项数量，同时设置截止时间。默认使用精确扫描；也提供近似索引，但须选择启用，且绝不会替你自动选择（参见调整密集索引）；任何索引提出的候选项在返回前，都会重新授权，并根据存储的向量重新评分。生成的观察结果和试验结果仍可能存在偏差。操作检查会在分派前验证声明的本地依赖项，但不会验证外部事务。不包括托管同步、模型训练和六种经过验证的原生框架集成。安全 · 部署 · 备份与恢复。

与我们共同构建

Mnemosyne 由 **Aristotle Intelligence Inc.（一家特拉华州公司）**开发，迄今完全由自有资金支持。如有高级记忆需求、集成讨论或投资者咨询，请联系 [email protected]。

可通过 GitHub issues 提交可复现的 Bug 和功能建议。请通过 SECURITY.md 私下报告漏洞。特别欢迎能改进证据留存、集成可靠性或可复现评估的贡献。

贡献指南 · 架构 · 更新日志 · 行为准则 · MIT 许可证 · 第三方声明