PLUR

PLUR — 让你的 Agent 共享同一份记忆

为 AI Agent 提供持久、开放的记忆——本地优先、零成本，可在多个 MCP 工具（Claude Code、Codex、Cursor、OpenCode、Hermes、OpenClaw）之间共享。你的 Agent 记忆是纯文本记忆印痕，可以读取、纠正和删除——而不是无法更改的权重。

plur.ai · 基准测试 · 记忆印痕规范 · npm · 对比

基准测试

PLUR 是记忆，不只是检索——因此我们从多个维度、在完整语料上进行测量，并公开测试框架，让你可以复现每个数字。

检索召回率——完整 LongMemEval-S（N=500），R@5，完全本地运行：

Stack	R@5	备注
仅 BM25	92.2%	无嵌入模型——完全隔离网络
混合（BGE-small，随附默认配置）	95.6%	本地嵌入模型；仅需下载一次模型
+ BGE-reranker-v2-m3	97.6%	本地交叉编码器，最高质量——可选启用，CPU 上 p50 约 5 秒

数据来自 plur-ai/plur-bench， 这是 PLUR 发布的所有基准测试数据的权威来源。如果仓库内的数据与 plur-bench 的数据不一致，以 plur-bench 为准——它是可复现的测试框架，也是 CI 用于回归检查的依据。

分块粒度、规范文档评分、语料 SHA256 均已固定——可在 plur-ai/plur-bench 复现。所有这些数据都不需要云端调用（使用可选的云端嵌入模型 openai-3-large 时，混合检索达到 97.0%）。更快的重排序器 ms-marco-minilm-l6（CPU 上 p50 约 245 毫秒，而 BGE 约需 5 秒）牺牲少许召回率，换取亚秒级延迟。

亲自运行——并告诉我们你的结果。 测试框架是 plur-ai/plur-bench：可在 CPU 上运行，本地模式无需 API 密钥，语料会自动获取并进行 SHA 校验。如果你运行了测试，我们非常期待看到你的数据——欢迎带着结果提交 issue 或发起讨论，尤其是结果与我们的数据不一致时。 独立复现比我们发布的任何数字都更有价值，我们也很乐意注明你的贡献。

检索 ≠ 答案准确率——我们分别报告这两项指标，绝不混为一谈。 使用重排序器技术栈时，端到端（LLM 评判）的答案准确率为 60.5%；将完整上下文直接放入提示词时为 52.0%，完全没有记忆时则为 5.5%。

对 Agent 任务的影响——相同任务，使用记忆与不使用记忆的对比：Haiku + PLUR 的表现胜过不使用 PLUR 的 Opus，成本约低 10 倍；在 Haiku、Sonnet 和 Opus 上，内部规则的测试结果均为 12–0。

运行特性——本地优先、零成本搜索，设计上保障数据主权。

更多测试正在进行：LoCoMo、Agent 任务套件、跨工具可移植性、记忆衰减／矛盾处理的正确性。 完整方法说明 →

这个想法

周一，你纠正了 Agent 的编码风格。周二，它又犯了同样的错误。你在 Cursor 中解释了自己的架构。到了晚上，Claude Code 却一无所知。

PLUR 解决了这个问题。安装一次，修正、偏好和惯例就会持久保存，并在不同会话、工具和设备之间保持一致。你的记忆以纯 YAML 文件的形式存储在本地磁盘上。没有云端、没有 API 调用，也没有黑箱。

有意思的是：在我们的工具路由和本地知识基准测试中，搭配 PLUR 记忆的 Haiku 表现优于不搭配 PLUR 记忆的 Opus——工具路由效果提升了 2.6 倍，成本却约低 10 倍。事实证明，瓶颈不在于模型的智能，而在于上下文。

模型是租来的；你的记忆是自己的。 无论下个月发布什么新模型，你都可以把 Haiku 换成 Opus——推理能力只是你无法掌控的商品。真正属于你的部分——Agent 对你的工作、修正和惯例的所有了解——不应存放在别人的云端，也不应被固化在你无法读取的权重中。PLUR 将其保存在本地磁盘上的纯文本文件中，采用开放格式，你可以检查、修正和删除。这才是真正拥有自己的智能。

安装

需要 Node.js 20 或更高版本。请安装这两个软件包，这样编辑器配置就能使用已安装的 MCP 服务：

npm install -g @plur-ai/cli@latest @plur-ai/mcp@latest
plur init
plur doctor

完成设置后，重启编辑器。plur doctor 会检查配置和 MCP 握手；如果搜索模型缺失且允许下载，它还会下载该模型。下载完成后，搜索将在本地运行；如果没有模型，则会回退到关键词搜索。

告诉你的 Agent

Set up PLUR memory for me: install @plur-ai/cli@latest and @plur-ai/mcp@latest globally, run `plur init`, then `plur doctor`. Show me any checks that fail.

Claude Code

plur init 会在 ~/.plur/ 创建本地存储，在 ~/.claude.json 注册用户级 MCP 服务，并将全局钩子写入 ~/.claude/settings.json。项目级 .mcp.json 是单独的项目级配置；~/.claude/mcp.json 不是用户级注册路径。Claude Code 发出 SessionEnd 时，钩子会注入记忆并关闭会话状态。升级 PLUR 后，请再次运行 init 以更新配置。

对于多项目设置，请使用 domain/scope 来分隔知识：

cd ~/projects/my-app
plur init --domain myapp --scope project:my-app

这会在项目中创建一个 .plur.yaml，其中的默认值会由钩子自动应用。在该项目中学到的 Engram 会添加标签；回忆时会按 scope 筛选，但始终包含全局知识。

根据内容为每个 engram 设置 scope。 Scope 不是每个会话只设置一次的选项——每次 plur_learn 调用都需要设置自己的 scope，具体取值取决于 engram 的内容。团队/共享知识应放入团队 scope（例如 PLUR Enterprise 使用的 group:<org>/<team>）；项目详情应放入 project:<name>；个人偏好则保留在本地。不要因为省略 scope 而让与团队相关的知识回退到 global——global 会泄漏到每个项目中，而且（配置了团队存储时）永远不会到达团队。plur_session_start 会列出令牌可写入的远程 scope。

升级

npm install -g @plur-ai/cli@latest @plur-ai/mcp@latest
plur init
plur doctor

重启编辑器，让它启动更新后的 MCP 服务。

Cursor

在项目根目录中运行：

plur init --cursor

这会写入 .cursor/mcp.json、.cursor/hooks.json 和 .cursor/rules/plur-memory.mdc。Cursor 使用精简的 cursor 工具配置：核心工具可直接使用，其他操作则可通过 plur_admin 使用。调用 plur_admin 并传入 { "action": "help" }，即可查看当前可用的名称和参数。

Codex

plur init --codex

通过 codex mcp add 在 ~/.codex/config.toml 中注册新的 MCP 服务，将生命周期钩子写入 ~/.codex/hooks.json（CODEX_HOME 可覆盖该目录），并在 AGENTS.md 中添加 PLUR 部分。检测到 ~/.codex/ 时会自动识别。

升级现有 Codex 安装：

npm install -g @plur-ai/cli@latest @plur-ai/mcp@latest
plur init --codex
plur doctor --codex

Init 会就地更新可识别的旧版 PLUR 启动固定项，同时保留环境设置、超时时间、工具策略和注释。它会保留较新的固定项以及自定义或 HTTP 服务。使用 --keep-codex-mcp 可保留有意设置的旧启动项。更改配置后，请重启 Codex。

对于使用 plur remote --token-env NAME 的远程存储，remote 和 init --codex 都会将所需变量名添加到 Codex 的 env_vars；它们绝不会将令牌值复制到配置中。启动 Codex 的进程也必须能够访问该变量。在 PowerShell 中导出变量，并不能证明单独启动的桌面应用已继承该变量。

plur doctor --codex 会使用 Codex 风格的环境过滤，从 Codex 用户配置中启动 MCP 命令，将其报告的版本与 CLI 进行比对，并报告令牌转发或令牌值缺失的情况。它不会检查项目/配置文件覆盖项、其他正在运行的应用的环境、钩子信任状态或远程写入。--no-handshake 会将运行时报告为未验证，并以非零状态退出。在确认桌面端配置完成前，请先在实际的 Codex 会话中验证能否保存并回忆测试记忆。原生 Windows 和 WSL2 有独立的主目录和注册项；请在你使用的每个环境中运行设置。

注入使用混合搜索（BM25 + 嵌入），如果嵌入器较慢或不可用，则会自动回退到 BM25。设置 PLUR_HOOK_HYBRID=0 可强制使用 BM25（也适用于 Antigravity 钩子；PLUR_CODEX_HYBRID 作为别名受到支持）。PLUR_HOOK_HYBRID_DEADLINE_MS 用于调整回退期限——请将其设置为低于你的运行环境钩子超时时间（Codex 为 25s，Antigravity 为 20s）。

**安装后有一个手动步骤：**打开 Codex，运行 /hooks，并信任 PLUR 条目。Codex 会为每个钩子生成指纹，并拒绝运行不受信任的钩子——但不会发出任何提示，既无警告，退出代码也为零。在信任这些钩子之前，记忆将永远不会加载。plur doctor 也会提示这一点。

OpenCode

plur init --opencode
plur doctor

这会将记忆插件和 MCP 工具添加到 ~/.config/opencode/opencode.json；如果不存在 .json 文件，则添加到现有的 opencode.jsonc。OPENCODE_CONFIG_DIR 优先；否则，XDG_CONFIG_HOME/opencode 会覆盖默认目录。

MCP 命令使用 Node，并在可用时使用已安装的 @plur-ai/mcp 入口。Init 会将旧版的精确 @plur-ai/opencode 固定项更新为 CLI 随附的插件版本，同时保留注释、格式和无关设置。较新的固定项、标签和未固定条目保持不变。使用 --keep-opencode-plugin 可保留有意设置的旧固定项。重启 OpenCode 以加载更改后的配置。插件详情。

可获得哪些集成

每个 MCP 客户端都可以调用 PLUR 的工具。只有部分客户端提供 适配器 ——也就是能让记忆自动加载、而不是等待 Agent 想起要加载的钩子和常驻上下文。没有适配器时，记忆回忆和学习完全取决于模型是否选择调用工具；在上下文压力下，这种方式的效果会大幅下降。

Harness	工具	自动注入 + 强制执行
Claude Code	✅	✅ 钩子 + CLAUDE.md
Codex	✅	✅ 钩子 + AGENTS.md（信任 /hooks 一次）
Cursor	✅	✅ 钩子 + 规则
OpenCode	✅	✅ 记忆插件 + MCP 工具
OpenClaw	✅	✅ ContextEngine 插件
Hermes	✅	✅ 插件
Antigravity CLI (agy)	✅	✅ 钩子 + AGENTS.md
Windsurf、Gemini CLI、其他 MCP 客户端	✅	❌ 仅工具

如果你的 Harness 位于最后一行，可以将 CLAUDE.md 中的 PLUR 部分粘贴到它自己的上下文文件（AGENTS.md、GEMINI.md 等）中作为临时方案——这样可以恢复指令层，但不会恢复自动注入。

Antigravity CLI (agy)

plur init --antigravity

将钩子和 MCP 服务写入 agy 的全局配置（~/.gemini/config/），并在 AGENTS.md 中添加 PLUR 部分。当 ~/.gemini/antigravity-cli/ 存在时会自动检测。无需信任步骤——agy 会在首次调用时运行已配置的钩子；只需重启 agy。

Antigravity 没有会话开始事件，也没有逐提示词钩子，因此 PLUR 会在 PreInvocation 中处理所有工作：逐提示词回忆从对话记录中读取；每次模型调用时，都会将本轮记忆作为临时消息重新注入，使其在工具调用期间保留，同时不会在历史记录中累积。

Gemini CLI 用户：Google 正在将 Gemini CLI 过渡到 Antigravity——安装 agy 并运行上面的命令。Gemini CLI 本身仍仅提供工具。

OpenClaw

openclaw plugins install @plur-ai/claw
openclaw config set plur.enabled true

就这样。PLUR 从此会在后台运行。无需更改工作流——像往常一样使用你的工具即可。更正内容会自动累积。

DeepSeek Harness

dsh plugin add @plur-ai/dsh

这是原生集成，并非 MCP 桥接。PLUR 会作为 Cordis 插件挂载，并将你的记忆印迹直接写入系统提示词，因此模型读取它们的方式与读取自身指令相同——无需调用工具、无需往返，也无需花费一个轮次来决定是否查找。每次组装时都会重新渲染该部分，而不是追加内容，因此会话运行期间记忆不会在上下文中累积。

仍会注册五个工具（plur_recall、plur_learn、plur_forget、plur_feedback、plur_status），供 Agent 在需要主动调用记忆时使用。默认情况下作用域为关闭状态——每个工作区都有自己的作用域，从其 .plur.yaml 中解析。

/plur 用于报告状态；/plur-memory 用于打开下方的记忆查看器。

Hermes Agent

pip install plur-hermes
npm install -g @plur-ai/cli

该插件会通过 Hermes 的插件系统自动注册。它会在每次调用大模型之前注入相关记忆，从 Agent 的响应中提取学习内容，并向 Agent 提供所有 PLUR 工具。Hermes 会调用 PLUR CLI。

Python SDK（LangChain、llama.cpp、脚本）

适用于非 Hermes 的 Python 环境：

pip install "plur-ai @ git+https://github.com/plur-ai/plur.git#subdirectory=packages/python"
npm install -g @plur-ai/cli   # bridge (required)

注意： plur-ai 尚未发布到 PyPI——在 #915 问题解决之前，请使用上面的 Git 安装方式。

from plur_ai import Plur

plur = Plur()
plur.learn("always use async generators for streaming LLM output")
results = plur.recall("streaming patterns")
context = plur.inject("write a streaming endpoint", limit=10)

plur-ai 会连接到与 Claude Code 和 OpenClaw 相同的磁盘存储——从 Python 写入的记忆会立即在所有工具中可见。LangChain 和 llama.cpp 集成示例，请参阅 packages/python/examples/。

验证是否正常工作

运行 plur doctor，然后让你的 Agent 调用 plur_status，并显示其记忆印迹数量和存储路径。默认的精简 MCP 配置会直接提供核心工具；如需查看其余操作及对应的架构，请使用 plur_admin 并传入 { "action": "help" }。

阅读你的记忆

plur dashboard

打开一个本地页面，列出每条记忆痕迹：学到了什么、实际回想起了什么，以及回想的频率。页面只读，仅限回环访问，由你自己的设备提供服务——不会上传任何内容。--port 可更改端口，--no-open 可跳过浏览器打开。在 DeepSeek Harness 中，只需访问 /plur-memory 即可打开同一页面。

支持 English 和中文；页面会跟随浏览器语言，也可使用 ?lang=zh。

查看实际效果

启动后，只需教你的 Agent 一次：

“在这个项目中始终使用 pnpm——npm install 会导致 CI 中的锁文件出问题。”

第二天开始一个新会话，然后询问：

You: How do I run the tests?

<plur-memory> 1 engram · project:my-api </plur-memory>

Agent: Use pnpm — you mentioned npm breaks the lockfile in CI:

  pnpm test                           # full suite
  pnpm test -- src/auth.test.ts       # single file

新会话。无需提醒。它记住了这条修正。

这就是 PLUR 发挥作用的时刻——Agent 会记住你只提过一次的项目约定，即使它不在任何可读取的文件中。

工作原理

PLUR 有两种存储原语：

记忆痕迹 — 可跨会话保留的已学知识。每条记忆痕迹都是一条带类型的断言（“始终使用蓝绿部署”“绝不向 main 强制推送”），包含：

• 激活度 — 会随时间衰减（ACT-R 模型），并在访问时增强的检索强度。过时的信息会自然减少注入，无需手动清理。
• 反馈信号 — 正面／负面评分，用于逐步优化注入质量
• 作用范围 — 分层命名空间（global、project:myapp、cluster:prod、service:api），用于控制记忆痕迹的适用范围
• 极性 — 自动区分“应该做”和“不应该做”的规则，从而将约束与指令分开注入
• 关联 — 与其他记忆痕迹的链接，包括在记忆痕迹被同时回想起时自动形成的共同访问边

事件记录 — 带时间戳的事件记录，用于记录“何时发生了什么”。每条事件记录都会保存摘要、时间戳、Agent 归属和渠道。可将事件记录用于事件时间线、会话日志和操作历史。可按时间范围、Agent 或渠道查询。

You correct your agent  →  engram created  →  YAML on your disk
Agent fixes an incident →  episode captured →  timeline searchable
Next session starts     →  relevant engrams injected  →  agent remembers
You rate the result     →  engram strengthens or decays  →  quality improves
Unused engrams          →  activation decays  →  naturally fade from injection

搜索完全在本地进行：BM25（结合 IDF 权重、TF 饱和度和长度归一化）+ BGE 嵌入 + Reciprocal Rank Fusion。零 API 调用，零单次查询成本。基准测试方法 →

插件（OpenClaw、Hermes）会自动从 Agent 对话中捕获所学内容——无需手动保存。Agent 的修正会自动变成记忆痕迹，无需你进行任何操作。

有关架构详情、激活模型和注入算法，请参阅完整的记忆痕迹规范。

开放格式

记忆痕迹采用开放且有版本管理的格式，而非黑箱。每条记忆痕迹都是纯 YAML，并根据已发布的 JSON Schema 进行验证。该 Schema 由引擎使用的同一份 Zod 源代码生成（Schema 位于 spec/ 中）。你可以阅读它、在 git 中对比差异、据此编写自己的工具，或基于相同格式构建不同的引擎——你的记忆不会被锁定在 PLUR 中。

用法

import { Plur } from '@plur-ai/core'

const plur = new Plur()

// Learn from a correction. The engine's read and write methods are async —
// they return promises so a `Plur` can be backed by a network store as well
// as by the default local YAML one.
await plur.learn('toEqual() in Vitest is strict — use toMatchObject() for partial matching', {
  type: 'behavioral',
  scope: 'project:my-app',
  domain: 'dev/testing'
})

// Recall (hybrid: BM25 + embeddings, zero cost)
const results = await plur.recallHybrid('vitest assertion matching')

// Inject relevant engrams into agent context. You get context blocks ready to
// paste into a prompt plus the IDs that went into them — not the engrams
// themselves. `budget` is the ceiling in tokens; selection fills it by relevance.
const injection = await plur.inject('Write tests for the user service', {
  scope: 'project:my-app',
  budget: 2000
})
console.log(injection.directives)   // also .constraints, .consider
console.log(`${injection.count} engrams, ${injection.tokens_used} tokens`)

// Feedback trains the system — rate anything you have an ID for, whether it came
// back from recall or went out in an injection (injection.injected_ids).
if (results[0]) await plur.feedback(results[0].id, 'positive')

// Capture an event (episode). Episode operations stay synchronous — they are
// backed by episodes.yaml, not the engram primary store.
plur.capture('Fixed CrashLoopBackOff on bee-3-4 by increasing memory limits', {
  agent: 'claude-code',
  channel: 'terminal'
})

// Query timeline
const incidents = plur.timeline({ agent: 'claude-code' })

// Sync across machines (use a private git remote — all engrams including private-visibility ones are pushed)
await plur.sync('[email protected]:you/plur-memory.git')

工具

工具	功能
plur_learn	存储更正、偏好或约定
plur_learn_batch	一次调用存储多个记忆印迹（批量去重 + 隔离每项失败）
plur_recall	检索相关记忆——默认使用混合检索（BM25 + 嵌入）；使用 mode:"keyword" 仅进行 BM25 检索
plur_inject_hybrid	在令牌预算范围内为当前任务选择记忆印迹
plur_feedback	评价相关性（随时间推移训练质量）
plur_forget	退役一条记忆（激活度会衰减，最终被清理）
plur_rescope	将现有记忆印迹移至另一个范围——从个人范围移至团队范围，或反向移动
plur_session_scope	在会话中途更改会话的默认写入范围
plur_capture	记录事件——事故、解决方案、会话里程碑
plur_timeline	按时间、Agent 或频道查询事件历史
plur_ingest	自动从文本中提取记忆印迹
plur_sync	通过 git 同步。personal 远程端会镜像所有内容（请使用私有仓库）；shared 远程端仅接收共享范围、非私有的记忆印迹
plur_status	检查系统运行状况和记忆印迹数量
plur_receipt	统计本地报告，显示记忆为你检索了哪些内容
plur_outbox	检查（并重试）存储不可用时排队等待写入的团队内容

发件箱

写入团队范围的内容会发送到该团队的远程存储。当存储无法访问时——VPN 未连接、服务器宕机、令牌过期——记忆印迹不会丢失，也不会被悄悄丢弃：它会连同队列元数据一起写入本地，并在下次会话启动时、执行 plur sync 时或按需重试。

队列不是一个目录。它存储在 engrams.yaml 中受影响记忆印迹的 structured_data._outbox 内，因此需要通过命令查看：

plur outbox            # what is queued, for which scope, how long, last error
plur outbox --flush    # retry now

Agent 也可以使用 plur_outbox 执行相同操作（传入 {flush: true} 进行重试），plur status 则会报告待处理数量。这两种方式都不会输出目标 URL 或令牌。

文件夹映射

~/.plur/folders.yaml 记录 PLUR 在每个文件夹中的行为，所有集成都遵循此配置：

设置	功能
plur: on	在此处照常使用记忆
plur: off	PLUR 在此处不执行任何操作
plur: ask	每个会话询问一次
scope: <s>	在此处保存的记忆所使用的默认范围
trusted: true	此文件夹的 .plur.yaml 可以设置其范围和团队服务
plur: remote-only + scope: <s>	记忆仅发送到团队服务中的 <s>；不会在此处读取或写入你的个人记忆（关于哪些内容会留在磁盘上，请参阅文档）

plur folders set ~/client-work --remote-only --scope group:acme/client
plur folders set ~/private --off
plur folders list

文件开头包含每项设置的注释示例；CLI 写入文件时会保留你的注释和顺序。详情请参阅 docs/folder-map.md，其中包括 remote-only 文件夹具体会拒绝哪些操作，以及团队服务宕机时会发生什么。

记忆回执

plur receipt（以及 plur_receipt MCP 工具）会显示记忆实际执行的操作——数据来自 PLUR 自身的检索历史记录，均为统计结果，从不进行估算：

Your Memory Receipt
===================
  2026-07-03 .. 2026-07-22  (71 sessions)

  423 times a memory you taught PLUR
  was put in front of the model.
  (plus 45 times an installed-pack memory)

  across 71 retrievals in 71 sessions
  drawing on 162 distinct engrams

  MOST-RELIED-ON
      34x  PLUR positioning thesis across every vertical: PLUR layers …
      28x  Datacore app CoS architecture: reasoning layer added on to…
      ...

  STORE HEALTH
       4,517   engrams stored (you: 3,746, packs: 771)
         162   retrieved at least once (4% of store)
       4,355   not retrieved since 2026-07-03 (96%)
    Over a short logging window a low rate is expected, not a fault —
    memory is meant to be selective, and much of the store predates logging.

（还会显示 REUSE 统计数据和覆盖率注意事项；此处因篇幅所限予以省略。）

它在本地运行且为只读，并且设计上不包含任何美元或令牌数量：使用订阅服务时，边际令牌成本为零，而避免重复探索所带来的价值无法通过这些数据衡量。回执只报告可统计的内容。激活率是存储在记录窗口内的覆盖率，并非质量评分——它本来就会比较低，并会随着记忆印迹的增加而下降。--days N 可缩短统计窗口；--json 会输出原始数据结构。（plur_receipt MCP 工具会返回相同数据，并附带一行 summary，向 Agent 传达这一背景。）

跨设备同步

plur.sync(remote) 底层使用 git：它会提交你的 engram 存储，并将其推送到你指定的远程服务。推送的内容取决于远程服务声明的类型（config.yaml 中的 sync.remote_type，或 remote_type 参数）：

• personal（默认）——在你自己的设备间备份／镜像。远程服务会接收所有推送的内容，包括 visibility: private 的 engram：私有可见性表示「不要在数据包中分享」，而不是「不要镜像到我自己的设备」，因此私有 engram 会有意地随你在不同设备间同步。因此，务必使用私有 git 远程服务（私有 GitHub/GitLab 仓库，或你自己的服务器）。只要存在私有 engram，PLUR 就会在同步结果中显示 warning。切勿将个人同步指向公共仓库。
• shared——团队可见的远程服务。只有具有共享系列范围（group:/project:/space:/team:/org:/public）且可见性非私有的 engram 才会被推送；个人系列 engram（local、global、user:*、agent:*）和私有可见性的 engram 则绝不会到达远程服务，这是由设计保证的。请注意，默认可见性为 private，因此共享远程服务只会接收那些主动设置了可见性的 engram——队友只能获得你选择分享的内容，不会有其他内容。同样的保证也适用于相关的存储文件（#686）：只有当某条 episode、candidate 或 tension 记录引用的每个 engram 都在推送集合中时，该记录才会被推送——由个人或私有 engram 派生的记录（例如 tension 的陈述快照、失败报告中的 episode）会留在本地；引用了筛选器无法解析的 engram 的任何记录也会留在本地。

在两种模式下，scope: local 的 engram 都是专为特定机器设计的（路径、本地端口、各主机的特殊情况），因此会从每次提交中剔除，绝不会到达任何远程服务。剔除发生在暂存的 blob 中：你的本地工作副本始终保留所有 engram。

基准测试详情

按类别统计的检索召回率，来自早前在仓库内运行的测试——完整的 LongMemEval-S（N=500），完全本地运行（BGE-small + BGE-reranker-v2-m3，分块 粒度）。其总体数值（98.0%）早于当前对相同技术栈进行的 plur-bench 测量结果（97.6%），且未按类别重新运行；类别分布仅供参考，上方的汇总表才是当前数据。

类别	R@5	R@10
单轮会话-助手	100.0%	100.0%
知识更新	100.0%	100.0%
单轮会话-用户	98.6%	100.0%
多轮会话	98.5%	100.0%
时间推理	97.7%	98.5%
单轮会话-偏好	86.7%	90.0%
总体	98.0%	99.0%

检索召回率（找到正确记忆）和端到端回答准确率（模型随后是否正确作答）是不同的维度——PLUR 会分别测量并报告，绝不会将两者混为一谈。上方的 Agent 影响数据来自同一任务的 A/B 测试（使用记忆 vs. 不使用记忆）。

完整方法说明 →

PLUR 与其他 Agent 记忆工具对比

Mem0、Letta（MemGPT）和 Zep 都解决了实际问题——即插即用的记忆 API（Mem0）、可自我管理的 Agent 操作系统（Letta）和时序知识图谱（Zep）。PLUR 则押注于将它们都未能同时提供的功能组合起来：

• 由你掌控的纯文本——engram 是人类可读的 YAML，你可以阅读、执行 git diff、编辑，并确切地将其删除。它们不是不透明的向量、Agent 状态块，也不是需要借助工具才能检查的图谱节点。
• 本地优先，零成本——结合 BM25 与本地嵌入，完全离线，无 API 费用（在完整的 LongMemEval-S 语料库上达到 98% 的 R@5，且无需调用云端——见上文）。
• 通过 git 与团队共享——plur sync 底层使用 git，因此同一份记忆会随你在不同设备间迁移，也能在团队中共享。大多数工具要么仅供单用户本地使用，要么面向云端团队；PLUR 两者兼具，且数据由你掌控。
• 跨工具使用——同一个 ~/.plur/ 存储可用于 Claude Code、Cursor、Windsurf、OpenClaw 和 Hermes。你的记忆不会被困在某个供应商的产品中。
• 能够学习和遗忘——基于反馈训练的检索机制，结合 ACT-R 衰减和按需矛盾扫描，而不是一个只增不减的存储库。

如果你需要托管式记忆 API 或时序知识图谱，请使用专为此打造的工具。如果你想要一种可以阅读、掌控、与团队共享并在不同工具间迁移的记忆，那就选择 PLUR。并列详情见：comparisons/。

PLUR 是什么——又不是什么

PLUR 是Agent 记忆——它会存储 AI Agent 在工作会话中学到的纠正意见、偏好、惯例和架构决策，并在这些内容相关时将其注入会话。

PLUR 不是通用搜索引擎、代码库索引器，也不是代码智能工具的替代品。它不会解析 AST、浏览类层次结构，也不会搜索你的源文件。如果你需要代码感知搜索（tree-sitter、语言服务器功能、符号查找），claude-mem 这类工具或 IDE 内置搜索才是合适的选择。

两者可以互为补充：

	PLUR	代码智能工具
存储	学到的知识（engrams）+ 事件时间线（episodes）	代码结构、符号、定义
搜索	Engram 回忆（对记忆使用 BM25 + 嵌入）	AST 遍历、符号查找、语义代码搜索
学习	来自 Agent 的纠正意见、反馈和使用模式	来自对源代码的静态分析
捕获	自动从对话中提取所学内容（通过插件）	N/A
衰减	是——未使用的记忆会逐渐淡化（ACT-R 模型）	否——代码索引反映当前状态
时间线	Episodes 会追踪事件的发生时间（事故、修复、决策）	仅 Git 日志
跨工具	任意 MCP 客户端（Claude Code、Cursor、Windsurf、OpenClaw、Hermes）	通常绑定到单一工具

虽然搜索是 PLUR 的核心功能之一（用于找到要注入的合适 engram），但搜索目标始终是 engram——而不是文件、代码或文档。PLUR 的混合搜索（BM25 + 嵌入 + RRF）针对简短的自然语言陈述进行了优化，而非源代码。

Packages

Package	Description
@plur-ai/core	Engram 引擎 — 学习、回忆、注入、搜索、衰减
@plur-ai/mcp	面向 Claude Code、Cursor、Windsurf 的 MCP 服务
@plur-ai/claw	OpenClaw ContextEngine 插件
@plur-ai/cli	CLI — plur learn / recall / inject / status
@plur-ai/dsh	DeepSeek Harness 插件 — 将 engram 放入提示词，无需调用工具
@plur-ai/opencode	opencode 插件 — 将 engram 放入提示词，无需调用工具
@plur-ai/migrate	存储迁移，随迁移目标版本一同发布
plur-hermes	Hermes Agent 插件（Python，通过 CLI 桥接）
plur-ai	Python SDK — 面向 LangChain、llama.cpp 和脚本的学习 / 回忆 / 注入功能
plur-langchain	LangChain BaseMemory + BaseChatMessageHistory 适配器

packages/ui 为内部组件 — 记忆查看器的页面，打包进 CLI 和 DeepSeek Harness 插件，而不是单独发布。它不在 npm 上。

架构

@plur-ai/core
├── engrams.ts           Engram CRUD + YAML persistence
├── episodes.ts          Episode capture + timeline queries
├── fts.ts               BM25 with IDF, TF saturation (k1/b), length normalization
├── embeddings.ts        BGE-small-en-v1.5, 384-dim, local ONNX
├── hybrid-search.ts     Reciprocal Rank Fusion
├── inject.ts            Context-aware selection + spreading activation
├── decay.ts             ACT-R activation decay
├── secrets.ts           Secret detection (API keys, passwords, tokens)
├── sync.ts              Git-based sync + file locking (O_EXCL)
├── storage.ts           Path detection + YAML I/O
└── storage-indexed.ts   Optional SQLite read index

@plur-ai/mcp          Wraps core as MCP tools
@plur-ai/claw          OpenClaw ContextEngine hooks (assemble/compact/afterTurn)
plur-hermes            Python plugin for Hermes Agent (auto inject/learn)
plur-ai                Python SDK — direct learn/recall/inject for scripts and frameworks

存储

所有内容都是纯 YAML。打开即可查看和编辑。

~/.plur/
├── engrams.yaml     # learned knowledge (source of truth)
├── episodes.yaml    # session timeline
├── config.yaml      # settings
└── engrams.db       # optional SQLite read index (auto-generated)

PLUR_PATH 可覆盖默认位置。

索引默认启用（index: true），后端根据存储大小选择，因此通常无需配置：

存储大小	后端	查询由什么处理
少于 5,000 个 engram	yaml	内存中的 BM25 + 精确余弦相似度
5,000 个及以上	pglite	嵌入式 Postgres + pgvector
50,000 个及以上	postgres	指向的 Postgres 服务 — 在 SQL 中执行 BM25；语义回忆分数在内存中计算（见下文）

除 postgres 外，所有层级都以 YAML 为事实来源（ADR-0001、 ADR-0005）— 索引是会自动重建的缓存，可随时删除。在 config.yaml 中设置 backend: 可显式固定某个层级。

关于 postgres 层级有一点需要说明，因为它是本表最重要的一行：core 不会将嵌入向量写入 Postgres 主存储 （ADR-0005 修订版）。关键词 / BM25 回忆在 SQL 中运行，但除非部署自行填充 engram_embeddings，否则该表会保持为空。因此，语义和混合回忆会退回到加载 engram 并在内存中评分 — 结果正确，但会产生该层级原本旨在避免的 O(N) 开销。适配器会在初始化架构时提示一次；vectorIndex: 'exact' 表示已知晓并将其静默。

sqlite（engrams.db，通过 better-sqlite3）是旧版索引， 不再自动选用。

要求

• Node.js 22+（在 HTTPS 代理后使用时，需为 22.21+ 或 24+，并设置 NODE_USE_ENV_PROXY=1）
• 至少 2GB RAM — 安装时，嵌入模型（ONNX 运行时）需要约 1GB。RAM 较少的服务器会跳过嵌入，搜索退回到 BM25 关键词匹配。

开发

git clone https://github.com/plur-ai/plur.git
cd plur
pnpm install && pnpm build && pnpm test

约 200 个文件中共有约 3,500 个测试。开发时可运行 pnpm test:watch。

贡献

• 错误报告 — 提交附有复现步骤的问题
• 功能请求 — 提交说明使用场景的问题
• 代码 — Fork、创建分支并提交 PR。必须包含测试。
• 集成 — 为其他工具构建 PLUR 支持

提交前：确保 pnpm test 通过、pnpm build 成功；未经讨论，不要在 core 中添加新的外部依赖。

约定：TypeScript、Zod 验证、Vitest、core 中不调用外部 API、YAML 存储、默认提供零成本搜索。

许可证

Apache-2.0