内容
<p align="center">
<a href="https://plur.ai"><img src="assets/plur-banner.png" alt="PLUR — 本地优先的共享内存，用于 AI 代理。Haiku + PLUR 优于 Opus（无 PLUR），成本降低约 10 倍。" width="100%"></a>
</p>
# PLUR — 您的代理共享同一内存
[](https://www.npmjs.com/package/@plur-ai/core)
[](https://github.com/plur-ai/plur/actions/workflows/ci.yml)
[](LICENSE)
[](https://github.com/plur-ai/plur/stargazers)
用于 AI 代理的持久内存。本地优先，零成本，适用于 MCP 工具。
[plur.ai](https://plur.ai) · [基准测试](https://plur.ai/benchmark.html) · [Engram 规范](https://plur.ai/spec.html) · [npm](https://www.npmjs.com/org/plur-ai)
## 基准测试
PLUR 是内存，而不仅仅是检索 - 因此我们在多个维度上进行衡量。
**检索召回率** — LongMemEval（R@5，块粒度）：
| 堆栈 | R@5 | 备注 |
|-------|-----|-------|
| **PLUR 混合 + 重新排序器** | **97.6%** | 完全本地的交叉编码器 - 无 API |
| PLUR 混合（openai-3-large 嵌入） | 97.0% | 可选的云端嵌入器 |
| PLUR BM25 仅 | 92.2% | 无嵌入器 - 完全隔离 |
**代理任务影响** — 相同的任务，有记忆 vs 没有：Haiku + PLUR 优于 Opus（无 PLUR），成本降低约 **10 倍**；规则 **12–0** 跨 Haiku、Sonnet 和 Opus。
**操作** — 本地优先，零成本搜索，数据主权设计。
*更多基准测试中...：LoCoMo，端到端答案准确性（N=500），代理任务套件，跨工具可移植性，衰减/矛盾正确性。* [完整方法论 →](https://plur.ai/benchmark.html)
## 想法
您周一纠正代理的编码风格。周二，它又犯了同样的错误。您在 Cursor 中解释架构。那晚，Claude Code 完全不知道。
PLUR 解决了这个问题。安装一次，纠正、偏好和约定在会话、工具和机器之间持续。您的内存存储为纯 YAML 文件在您的磁盘上。无需云，无需 API 调用，无需黑盒。
有趣的部分：在我们的工具路由和本地知识基准测试中，**Haiku 搭配 PLUR 内存优于 Opus（无 PLUR）** - 在工具路由上好 2.6 倍，成本降低约 10 倍。结果表明瓶颈不是模型智能，而是上下文。
## 安装
### 告诉您的代理
将以下内容粘贴到您的编码代理（Claude Code，Cursor，Windsurf，OpenClaw）：
```text
为我设置 PLUR 内存：运行 `npx @plur-ai/mcp init`，然后检查我的 PLUR 状态以确认它是否有效。
```
您是否更喜欢引导式设置？ [plur.ai](https://plur.ai) 具有适用于您的工具的精确配置 - Claude Code，Cursor，Windsurf 或 OpenClaw。
### 手动设置（Claude Code）
一条命令设置所有内容 - 存储，MCP 配置和 Claude Code 钩子：
```bash
npx @plur-ai/mcp init
```
这会创建 `~/.plur/` 用于存储，将 PLUR 添加到您的 `.mcp.json` 中，并为自动 engram 注入安装 Claude Code 钩子。PLUR **全局安装** - 一个 MCP 服务器，一个存储库，可在每个项目中使用。您只需运行一次 init。
对于**多项目设置**，使用域/范围来分隔知识：
```bash
cd ~/projects/my-app
npx @plur-ai/cli@0.9.4 init --domain myapp --scope project:my-app
```
这会在项目中创建一个 `.plur.yaml`，并使用默认设置，钩子自动应用。项目中学习的 engrams 被标记；召回过滤器按范围过滤，但始终包括全局知识。
**按 engram 设置范围，按内容。**范围不是一次会话设置 - 每个 `plur_learn` 调用都有自己的范围，从 engram 所属的内容中选择。团队/共享知识进入团队范围（例如 `group:<org>/<team>`，由 PLUR Enterprise 使用）；项目详细信息进入 `project:<name>`；个人偏好保留本地。不要让团队相关的知识回退到 `global`，省略范围 - `global` 泄漏到每个项目中（如果配置了团队存储），则永远不会到达团队。`plur_session_start` 列出令牌可以写入的远程范围。
### 全局安装（更快启动）
```bash
npm install -g @plur-ai/mcp
plur-mcp init
```
### OpenClaw
```bash
openclaw plugins install @plur-ai/claw
openclaw config set plur.enabled true
```
就是这样。PLUR 从这里开始在后台工作。无需更改工作流程 - 只需像平常一样使用您的工具。纠正会自动累积。
### Hermes 代理
```bash
pip install plur-hermes
npm install -g @plur-ai/cli@0.9.4
```
该插件通过 Hermes 的插件系统自动注册。它在每次 LLM 调用之前注入相关的记忆，提取代理响应中的学习内容，并向代理公开所有 PLUR 工具。Hermes 调用 PLUR CLI；当前验证的配对是 `plur-hermes==0.9.4` 和 `@plur-ai/cli@0.9.4`。
### 验证它是否有效
询问您的代理：*“我的 PLUR 状态是什么？”* - 它应该调用 `plur_status` 并返回您的 engram 数量和存储路径。
## 它是如何工作的
PLUR 有两个存储原语：
**[Engrams](https://plur.ai/spec.html)** - 持久的学习知识，跨会话持续存在。每个 engram 是一个有类型的断言（“始终使用蓝绿色部署”，“从不强制推送到 main”），具有：
- **激活** - 检索强度随时间衰减（ACT-R 模型），并在访问时加强。过时的事实会随着时间的推移自然消退，不需要手动清理。
- **反馈信号** - 正/负评级，随时间训练注入质量
- **范围** - 分层命名空间（`global`，`project:myapp`，`cluster:prod`，`service:api`），控制 engram 应用的位置
- **极性** - “做”与“不做”规则的自动分类，以便约束与指令分开
- **关联** - 与其他 engram 的链接，包括在 engram 一起回忆时自动形成的共访问边缘
**事件** - 时间戳事件记录，用于记录“发生了什么”。每个事件都捕获摘要、时间戳、代理属性和通道。使用事件记录时间线、会话日志和操作历史记录。按时间范围、代理或通道查询。
```
您纠正您的代理 → 创建 engram → YAML 存储在您的磁盘上
代理修复事件 → 捕获事件 → 时间线可搜索
下一个会话开始 → 注入相关 engram → 代理记住
您评估结果 → engram 加强或衰减 → 质量提高
未使用的 engram → 激活衰减 → 自然消退
```
搜索是完全本地的：BM25（带有 IDF 加权、TF 饱和度和长度归一化）+ BGE 嵌入 + 互惠排名融合。零 API 调用，零每次查询成本。 [基准测试方法 →](https://plur.ai/benchmark.html)
插件（OpenClaw，Hermes）自动从代理对话中捕获学习内容 - 无需手动保存。代理的纠正变成 engram，无需您做任何事情。
查看 [完整的 engram 规范](https://plur.ai/spec.html)，了解架构细节、激活模型和注入算法。
## 开放格式
engram 是一个**开放的、版本化的格式** - 不是一个黑盒。每个 engram 都是一个纯 YAML 文件，根据发布的 [JSON Schema](https://plur.ai/spec.html) 验证，该模式由与引擎使用的相同 Zod 源代码生成（模式位于 [`spec/`](spec/) 中）。阅读它，在 git 中进行差异对比，编写自己的工具，或在同一格式上构建不同的引擎 - 您的内存不锁定到 PLUR。
## 用法
```typescript
import { Plur } from '@plur-ai/core'
const plur = new Plur()
// 从纠正中学习
plur.learn('Vitest 中的 toEqual() 是严格的 - 使用 toMatchObject() 进行部分匹配', {
type: 'behavioral',
scope: 'project:my-app',
domain: 'dev/testing'
})
// 回忆（混合：BM25 + 嵌入，零成本）
const results = await plur.recallHybrid('vitest 断言匹配')
// 将相关 engram 注入代理上下文
const { engrams } = plur.inject('为用户服务编写测试', {
scope: 'project:my-app',
limit: 15
})
// 反馈训练系统
plur.feedback(engram.id, 'positive')
// 捕获事件（事件记录）
plur.capture('通过增加内存限制解决了 bee-3-4 上的 CrashLoopBackOff 问题', {
agent: 'claude-code',
channel: 'terminal'
})
// 查询时间线
const incidents = plur.timeline({ agent: 'claude-code' })
// 跨机器同步
plur.sync('git@github.com:you/plur-memory.git')
```
### MCP 工具
| 工具 | 功能 |
|------|-------------|
| `plur_learn` | 存储纠正、偏好或约定 |
| `plur_recall_hybrid` | 检索相关记忆（BM25 + 嵌入） |
| `plur_inject_hybrid` | 为当前任务选择相关 engram |
| `plur_feedback` | 评估相关性（随时间训练质量） |
| `plur_forget` | 淘汰记忆（激活衰减，最终修剪） |
| `plur_capture` | 记录事件 - 事件、解决、会话里程碑 |
| `plur_timeline` | 按时间、代理或通道查询事件历史 |
| `plur_ingest` | 自动从文本中提取 engram |
| `plur_sync` | 通过 git 在设备之间同步 |
| `plur_status` | 检查系统健康状况和 engram 数量 |
## 基准测试详情
每个类别的检索召回率（混合 + openai-3-large 嵌入，块粒度，LongMemEval）：
| 类别 | R@5 | R@10 |
|----------|-----|------|
| 单会话助手 | 100.0% | 100.0% |
| 知识更新 | 98.7% | 100.0% |
| 单会话用户 | 98.6% | 100.0% |
| 多会话 | 97.7% | 99.2% |
| 时间推理 | 94.0% | 97.0% |
| 单会话偏好 | 93.3% | 96.7% |
检索召回率（找到正确的记忆）和端到端答案准确率（模型是否正确回答）是**不同的轴** - PLUR 分别衡量和报告它们，从不混淆。上述代理影响数据来自同一任务的 A/B 运行（有记忆 vs 没有）。
[完整方法论 →](https://plur.ai/benchmark.html)
## PLUR 是什么 - 不是什么
PLUR 是**代理内存** - 它存储 AI 代理在工作会话期间学习到的纠正、偏好、约定和架构决策，并在它们相关时注入。
PLUR **不是** 通用搜索引擎、代码库索引器或代码智能工具的替代品。它不解析 AST、不导航类层次结构、不搜索源文件。如果您需要代码感知搜索（树状遍历、语言服务器功能、符号查找），工具如 [claude-mem](https://github.com/skydeckai/claude-mem) 或 IDE 内置搜索是正确的选择。
这两个是互补的：
| | PLUR | 代码智能工具 |
|---|------|------------------------|
| **存储** | 学习知识（engrams）+ 事件时间线（episodes） | 代码结构、符号、定义 |
| **搜索** | engram 回忆（BM25 + 嵌入内存） | AST 遍历、符号查找、语义代码搜索 |
| **学习** | 来自代理纠正、反馈、使用模式 | 来自源代码的静态分析 |
| **捕获** | 自动从对话中提取学习内容（通过插件） | 不适用 |
| **衰减** | 是 - 不使用的记忆会淡出（ACT-R 模型） | 否 - 代码索引反映当前状态 |
| **时间线** | 事件跟踪发生的时间（事件、修复、决策） | 仅 Git 日志 |
| **跨工具** | 任意 MCP 客户端（Claude Code、Cursor、Windsurf、OpenClaw、Hermes） | 通常绑定到一个工具 |
虽然搜索是 PLUR 的核心部分（找到正确的 engram 进行注入），但搜索目标始终是 engram - 不是文件、代码、文档。PLUR 的混合搜索（BM25 + 嵌入 + RRF）针对短自然语言断言进行了优化，而不是源代码。
## 软件包
| 软件包 | 描述 |
|---------|-------------|
| [`@plur-ai/core`](packages/core) | engram 引擎 - 学习、回忆、注入、搜索、衰减 |
| [`@plur-ai/mcp`](packages/mcp) | 用于 Claude Code、Cursor、Windsurf 的 MCP 服务器 |
| [`@plur-ai/claw`](packages/claw) | OpenClaw ContextEngine 插件 |
| [`plur-hermes`](packages/hermes) | Hermes 代理插件（Python，通过 CLI 桥接） |
## 架构
```
@plur-ai/core
├── engrams.ts Engram CRUD + YAML 持久性
├── episodes.ts 事件捕获 + 时间线查询
├── fts.ts 带有 IDF、TF 饱和度（k1/b）和长度归一化的 BM25
├── embeddings.ts BGE-small-en-v1.5，384-dim，本地 ONNX
├── hybrid-search.ts 互惠排名融合
├── inject.ts 上下文感知选择 + 扩散激活
├── decay.ts ACT-R 激活衰减
├── secrets.ts 机密检测（API 密钥、密码、令牌）
├── sync.ts 基于 git 的同步 + 文件锁定（O_EXCL）
├── storage.ts 路径检测 + YAML I/O
└── storage-indexed.ts 可选 SQLite 读取索引
@plur-ai/mcp 包装核心作为 MCP 工具
@plur-ai/claw OpenClaw ContextEngine 钩子（assemble/compact/afterTurn）
plur-hermes Hermes 代理插件（CLI 子进程桥接）
```
### 存储
一切都是纯 YAML。打开它，阅读它，编辑它。
```
~/.plur/
├── engrams.yaml # 学习知识（源代码）
├── episodes.yaml # 会话时间线
├── config.yaml # 设置
└── engrams.db # 可选 SQLite 读取索引（自动生成）
```
`PLUR_PATH` 覆盖默认位置。
对于大型存储库（>1k engram），启用 SQLite 读取索引以加快过滤查询。 在 `config.yaml` 中添加 `index: true`。 YAML 文件保持真实 - `.db` 是一个缓存，自动重新生成。 可以随时删除它。
## 需求
- **Node.js 18+**
- **2GB RAM 最低** - 嵌入式模型（ONNX 运行时）需要 ~1GB 进行安装。 在 RAM 较少的服务器上，嵌入式搜索会回退到 BM25 关键字匹配。
## 开发
```bash
git clone https://github.com/plur-ai/plur.git
cd plur
pnpm install && pnpm build && pnpm test
```
~340 个测试，分布在 27 个文件中。 `pnpm test:watch` 用于开发。
## 贡献
- **错误报告** - 带有重现步骤的问题
- **功能请求** - 描述用例的问题
- **代码** - 分叉、分支、PR。 需要测试。
- **集成** - 为其他工具构建 PLUR 支持
提交前：`pnpm test` 通过，`pnpm build` 成功，核心中没有新增外部依赖。
约定：TypeScript，Zod 验证，Vitest，核心中没有外部 API，YAML 存储，默认零成本搜索。
## 许可证
Apache-2.0
