内容
<div align="center">
# PAXM
### 停止为每个新的编码代理会话重复解释你的项目。
[](https://github.com/pax-beehive/paxm/actions/workflows/ci.yml)
[](https://github.com/pax-beehive/paxm/releases/latest)
[](go.mod)
[](https://github.com/pax-beehive/paxm/releases/latest)
PAXM 将决策、约定和工作上下文带入后续的 Codex、Claude Code、OpenCode、Pi 和 MCP 会话中。可以在本地使用 SQLite 开始，无需账户、API 密钥、嵌入或额外的内存层模型调用。以后可以更换内存提供商而无需重新连接每个代理。
[为 Codex 安装](#Codex 插件) · [安装 CLI](#OpenCode、Pi、CLI 或 MCP) · [查看结果](#安装后有什么变化) · [文档](#文档)
</div>
## 安装后有什么变化
在一个会话中，记录一个决定：
```bash
paxm remember --profile ltm --text \
"生产环境部署通过 GitHub Actions 进行；绝不从笔记本电脑部署"
```
在后续会话中，Codex、Claude Code、OpenCode、Pi 或 MCP 客户端可以恢复它：
```bash
paxm recall --query "我们如何部署生产环境？"
```
启用被动集成后，paxm 在代理响应之前回忆相关上下文，并在完成后持久捕获完成的内容。提供商的延迟或故障不会阻止编码会话。
实际效果：
- **新会话恢复项目上下文**，而不是要求您重述架构决策、约定和操作约束。
- **一个内存路径适用于所有代理。** 从 Codex 捕获的决策可以从 Claude Code、OpenCode、Pi 或任何 MCP 客户端回忆。
- **您的存储始终是您的选择。** 从本地 SQLite 开始，连接 Zep、Mem0、MemOS 或 OpenViking，或通过 JSON-RPC 引入私有提供商。
- **您保留控制权。** 凭证、钩子信任、路由、数据位置、禁用、卸载和回滚仍然由用户拥有。
## 快速开始
选择您已经使用的代理。Codex 插件是完整的活动和被动内存循环的最短路径。
### Codex 插件
```bash
codex plugin marketplace add pax-beehive/paxm --ref paxm-memory-v0.1.4
codex plugin add paxm-memory@pax-agent-nexus
curl -fsSL https://github.com/pax-beehive/paxm/releases/latest/download/install.sh | bash
paxm setup --integration codex-plugin
```
启动新的 Codex 任务，并在 `/hooks` 询问时信任 Pax Agent neXus 钩子。显式安装程序下载最新的已发布 paxm 二进制文件。插件注册活动内存技能并拥有被动 Codex 钩子；它从不安装二进制文件、写入凭证或绕过钩子信任。
验证第一次成功的循环，然后再依赖被动内存：
```bash
paxm config doctor
paxm remember --profile stm --text "PAXM_FIRST_RECALL_OK"
paxm recall --query "PAXM_FIRST_RECALL_OK"
paxm history --days 1
```
在安装前设置 `PAXM_VERSION` 以获取可复制的版本或回滚。提供商凭证仍然由用户管理。
### Claude Code 插件
安装 paxm CLI，然后安装 Claude Code 插件：
```bash
curl -fsSL https://github.com/pax-beehive/paxm/releases/latest/download/install.sh | bash
claude plugin marketplace add pax-beehive/paxm
claude plugin install paxm-claude@pax-memory
paxm setup --integration claude-plugin
```
Claude 插件包括活动内存技能、paxm MCP 服务器和五个生命周期钩子：`SessionStart`、`UserPromptSubmit`、`PostToolUse`、`PostToolUseFailure` 和 `Stop`。
### OpenCode、Pi、CLI 或 MCP
安装最新版本并运行交互式设置。默认 SQLite 提供商使适配器在无需创建帐户或 API 密钥的情况下可用。
```bash
curl -fsSL https://github.com/pax-beehive/paxm/releases/latest/download/install.sh | bash
paxm setup
paxm config doctor
```
`paxm setup` 是用户选择稳定用户 ID、提供商和被动代理集成的场所。选定的代理默认为 `codex-todd` 等 ID，可以在交互式设置期间重命名。使用上下箭头移动，空格键切换，Enter 键确认。
可选的团队 ID 创建明确的持久写入配置文件，例如 `team-pax-core`；非交互式设置可以传递 `--user-id todd --team-id pax-core`。
活动回忆技能仍然由用户安装。SQLite 无需 API 密钥；Zep、Mem0、MemOS 和 OpenViking 等远程提供商需要在设置期间提供连接详细信息。
SQLite 健康检查必须允许创建 WAL/SHM 文件到配置的数据库旁边。沙盒可以读取数据库但无法写入其父目录，可能会报告 SQLite 错误 14。
为沙盒评估使用隔离的可写 SQLite 路径。相同的配置在实际代理进程中可能是健康的。
当 Codex 使用捆绑的 `paxm-memory` 插件时，让插件拥有 Codex 的钩子，这样 paxm 就不会注册重复的全局钩子：
写入和回忆内存：
```bash
paxm remember --profile ltm --text "我们选择 SQLite 作为本地内存层"
paxm recall --query "本地内存层"
paxm history --days 7
```
在设置期间选择 OpenCode 以在 `~/.config/opencode/plugins/` 下安装全局本地插件。选择 Pi 以安装其被动扩展。任何 MCP 兼容客户端都可以使用 `paxm mcp serve --agent codex` 而无需被动钩子；将 `codex` 替换为配置的客户端标识。
## SQLite 质量预览
SQLite 为新用户提供了一个完整的本地内存循环，无需选择或部署专用内存系统。它使用 FTS5 和 BM25 检索，具有转折级别的内存和确定性的、查询聚焦的摘录。内存摄入和检索不调用任何外部 LLM 或嵌入服务。
在最初的 30 个问题 LoCoMo 代理评估中，SQLite 转折内存成功回答了 13 个问题，而 Mem0 产品默认值为 11 个。
| 内存臂 | 成功答案 | 平均令牌 F1 | 内存层中的外部模型 |
| --- | ---: | ---: | --- |
| paxm SQLite 转折内存 | 13 / 30 | 0.4211 | 无 |
| Mem0 产品默认值 | 11 / 30 | 0.3811 | GPT-5 mini + OpenAI 嵌入 |
这是探索性结果，而不是官方 LoCoMo 分数或证明 SQLite 广泛优于 Mem0。它涵盖了 OpenCode 和 DeepSeek V4 Flash 的一次平衡对话，使用确定性令牌 F1。参见 [方法和局限性](evals/locomo/README.md)。
## 工作原理
PAXM 是一个内存适配器，而不是另一个托管内存服务：
```text
AI 代理 -> CLI / MCP / 技能 / 钩子 -> paxm -> 任意内存提供商
```
代理通过两种方式到达 paxm：
| 路径 | 入口点 | 最适合 |
| --- | --- | --- |
| 主动 | CLI、MCP、技能 | 刻意回忆、显式写入、检查 |
| 被动 | 代理生命周期钩子 | 提示时间回忆和自动转折捕获 |
两种路径都使用相同的运行时和提供商路由器。过滤、配置文件、排名、超时、遥测和提供商行为在代理表面保持一致。
被动写入提交到本地持久队列，然后再交付给提供商。缓慢或不可用的提供商在后台重试，而不是阻塞代理。
被动回忆默认使用 `800ms` 的总体预算和 `250ms` 的每个提供商预算。它返回健康的局部结果并记录下游超时。
### 查看它在运动中
<details>
<summary><strong>一个代理表面，任意内存提供商</strong></summary>
<br>
<p align="center">
<img src="docs/assets/paxm-provider-routing.gif" width="900" alt="概念动画，显示 AI 代理使用 PAXM 将内存请求路由到 SQLite、OpenViking、Zep、Mem0 和私有 JSON-RPC 提供商">
</p>
PAXM 在配置文件选择提供商、故障策略、排名和超时期间保持面向代理的契约稳定。SQLite 是零设置默认提供商，而不是必需的存储后端。
</details>
<details>
<summary><strong>被动回忆和持久后台写入</strong></summary>
<br>
<p align="center">
<img src="docs/assets/paxm-passive-memory.gif" width="900" alt="概念动画，显示 PAXM 钩子为代理回忆上下文并通过持久后台队列传递完成的内容">
</p>
生命周期钩子在模型请求之前回忆上下文，并在完成后捕获完成的内容。写入进入本地持久队列，然后再交付给提供商，因此提供商延迟不会阻塞代理。
</details>
阅读详细的 [架构](docs/architecture.md) 和 [提供商适配器契约](docs/provider-adapter-contract.md)。
## 代理和提供商
### 代理表面
| 代理/客户端 | 主动 | 被动回忆 | 被动写入 |
| --- | :---: | :---: | :---: |
| Codex | CLI、MCP、技能 | 钩子 | 钩子 |
| Claude Code | CLI、MCP、技能 | 钩子 | 钩子 |
| Pi | CLI、MCP、技能 | 扩展 | 扩展 |
| 任意 MCP 客户端 | MCP 工具 | — | — |
### 内存提供商
| 提供商 | 模式 | 备注 |
| --- | --- | --- |
| SQLite | 默认，内置 | 零设置转折内存；无需 API 密钥、LLM 或嵌入 |
| Zep | 内置 | 用户或图范围 |
| Mem0 | 内置 | 自托管 REST API |
| Mem0 Cloud | 内置 | 托管平台 API，支持异步 v3 写入/搜索 |
| MemOS | 内置 | 自托管产品 API，按内存立方体范围 |
| MemOS Cloud | 内置 | 托管 OpenMem API，支持令牌身份验证 |
| OpenViking | 内置 | 自托管会话提取和语义内存搜索 |
| 自定义 JSON-RPC | 适配器 | 引入现有的或私有的内存系统 |
启用多个提供商实例同时使用。回忆和写入配置文件控制路由、必需或最佳努力行为、排名权重、阈值、内存层和超时。
### 自托管 OpenViking
OpenViking 支持连接 paxm 到用户操作的 OpenViking 服务器。写入通过 OpenViking 会话记录并提交以进行异步内存提取。回忆使用 `/api/v1/search/find` 通过语义内存搜索。
运行 `paxm setup`，选择 OpenViking，并提供自托管的基准 URL 和 API 密钥。然后，OpenViking 可以参与与 SQLite 或任何其他提供商相同的回忆和写入配置文件，具有必需或最佳努力路由和提供商特定的超时。
## MCP 服务器
以本地 stdio MCP 服务器的身份运行 paxm：
```bash
paxm mcp serve --agent codex
```
```json
{
"command": "paxm",
"args": ["mcp", "serve", "--agent", "codex"]
}
```
服务器暴露四个聚焦的工具：
- `paxm_recall`
- `paxm_remember`
- `paxm_history`
- `paxm_config_doctor`
设置、凭证管理、钩子安装和回填在 MCP 之外，以便代理无法悄悄接管用户的配置。
写入带有用户、代理和命名个人/团队范围的 provenance。回忆不按该范围过滤：CLI、MCP 和被动注入用其源范围标记每个结果，而提供商原生路由和 ACL 仍在提供商的控制之下。
## 代理集成
### Codex 插件
Codex 插件包含 paxm 设置技能、主动内存技能和原生 Codex 钩子。它不安装提供商凭证或绕过钩子信任。
使用 `paxm setup --integration codex-plugin`，只有插件拥有 Codex 生命周期钩子。
### Claude Code 插件
Claude Code 插件是一个一流的集成，而不是一个通用的设置垫片。它包含技能、MCP 服务器和五个原生生命周期钩子。
设置删除只有遗留的 paxm 管理的 Claude 钩子，保留无关的钩子，并记录 `claude-plugin` 所有权。
### Pi 扩展
Pi 支持通过 `paxm setup` 安装。扩展程序处理被动提示回忆，并将可见的用户、助手和工具事件缓冲到一个内存中，同时排除思考块。
### OpenCode 插件
OpenCode 支持作为依赖项免费的全局插件安装。插件使用 OpenCode 的 `chat.message` 和模型消息转换钩子进行被动回忆。
在 `session.idle` 时，它通过官方客户端读取已完成的会话并写入持久转折。它捕获可见的用户和助手文本，同时排除推理和工具有效载荷。
生成的插件位于 `~/.config/opencode/plugins/paxm.ts`，或在配置时位于 `OPENCODE_CONFIG_DIR`/`XDG_CONFIG_HOME` 下。
参见完整的 [配置指南](docs/config.md)，了解生成的路径、事件映射、配置文件设置和卸载行为。
## 默认可靠性
- 钩子确认仅等待本地队列事务。
- 提供商交付是可恢复的，并在后台重试。
- 可选提供商故障不会丢弃健康提供商的结果。
- 卡住的提供商由其超时和单调用舱壁限制。
- 写入提供商路由默认超时为 30 秒；可选故障保持隔离，而必需提供商故障返回给调用者。
- 回忆 provenance 在被动写入之前被剥离，以防止内存回声。
- 确切 LTM 合并限制重复累积。
- SQLite 保留具有明确会话、转折和时间边界的已完成代理转折。
- 遥测默认存储哈希和长度，而不是原始回忆查询。
历史导入也是可恢复的：
```bash
paxm backfill scan --agent codex --before 2026-07-09
paxm backfill run --agent codex --provider mem0-company --background
paxm backfill status --agent codex --provider mem0-company
```
## 性能
基准测试使用运行时生成的临时数据集，模拟真实的被动代理工作负载；基准测试存储库中不提交任何基准测试语料库。
在 Apple M4 参考机器上：
| 工作负载 | 适配器延迟 |
| --- | ---: |
| 128 KiB SQLite 写入 | 1.84 毫秒 |
| 2 MiB SQLite 写入 | 14.31 毫秒 |
| 10 项 / 1.25 MiB 批次 | 12.36 毫秒 |
| 从 100,000 条短内存中回忆 | 0.54 毫秒 |
| 从 10,000 x 32 KiB 内存中回忆 | 0.61 毫秒 |
这些数字衡量适配器的性能，而不是端到端代理响应时间。参见 [SQLite 适配器基准测试](docs/benchmarks.md)，获取数据集、命令、分配和机器详细信息。
## 评估
paxm 将确定性回归套件与付费的、真实代理质量评估分开。CI 保护运行时行为；选择加入基准测试衡量内存是否有助于代理正确回答。
存储库包括确定性生产路径评估：
```bash
go run ./cmd/paxm eval run --suite evals/baseline
go run ./cmd/paxm eval run --suite evals/conversation-write
```
- 一个 100 例检索套件报告召回@K、精度@K、MRR、假阳性率、延迟和类别级别结果。
- 一个 50 例对话到写入套件检查录取、回忆、禁止片段、元数据保留和适配器契约行为。
CI 在每次推送到 `main` 和每个拉取请求时运行单元测试、vet、检索报告和适配器写入契约。
选择加入的 [LoCoMo 代理基准测试](evals/locomo/README.md) 演练真实的 OpenCode 会话和生产 MCP 或被动回忆。
[跨代理基准测试](evals/cross-agent/README.md) 测试一个代理的经验是否帮助另一个避免相同的失败。
付费代理评估从不运行在普通的 CI 中。它们的报告将内存层成本与回答模型成本分开，并声明其证据限制。
## 文档
| 指南 | 内容 |
| --- | --- |
| [配置](docs/config.md) | 提供商、配置文件、代理、钩子、遥测 |
| [架构](docs/architecture.md) | 运行时模块和数据流 |
| [提供商契约](docs/provider-adapter-contract.md) | 实现内存适配器 |
| [基准测试](docs/benchmarks.md) | 被动工作负载数据集和结果 |
| [LoCoMo 评估](evals/locomo/README.md) | 真实代理内存质量方法论 |
| [发布指南](docs/release.md) | 构建、校验和、标签和发布 |
| [路线图](docs/roadmap.md) | 当前产品方向 |
## 社区
- 在 [GitHub Discussions](https://github.com/pax-beehive/paxm/discussions) 中提问、分享成功的工作流程和讨论早期想法。
- 通过存储库的结构化 [问题表单](https://github.com/pax-beehive/paxm/issues/new/choose) 报告可重现的错误或请求需求支持的集成。
- 在提出重大更改之前阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。
- 根据 [SECURITY.md](SECURITY.md) 私密报告疑似漏洞。
## 开发
```bash
go test ./...
go vet ./...
go build -o /tmp/paxm ./cmd/paxm
/tmp/paxm --config /tmp/paxm-dev/config.yaml setup --force
```
## 版本
版本涵盖 macOS、Linux 和 Windows，支持 `amd64` 和 `arm64`。发布的存档包括 `SHA256SUMS`，安装程序在替换二进制文件之前会验证选定的存档。
参见 [发布指南](docs/release.md)，了解验证、标签、资产和安装程序烟雾测试要求。
