pax-beehive/paxm

## 安装后的改变 在一个会话中记录一项决策： ``` paxm remember --profile ltm --text \ "Production deploys run through GitHub Actions; never deploy from a laptop" ``` 在之后的会话中，Codex、Claude Code、OpenCode、Pi 或 MCP client 可以 恢复它： ``` paxm recall --query "how do we deploy production?" ``` 启用被动集成后，paxm 会在 agent 响应前召回相关上下文，并在事后持久化捕获已完成的对话轮次。Provider 延迟或失败不会阻塞 coding 会话。 实际效果： - **新会话基于项目上下文恢复**，而不是让你重新陈述架构决策、约定和操作限制。 - **一条 memory 路径适用于所有 agent。** 从 Codex 捕获的决策可以从 Claude Code、OpenCode、Pi 或任何 MCP client 召回。 - **你的存储由你决定。** 可以从本地 SQLite 开始，接入 Zep、 Mem0、MemOS 或 OpenViking，或者通过 JSON-RPC 引入私有 provider。 - **你始终拥有控制权。** 凭据、hook 信任、路由、数据位置、 禁用、卸载和回滚始终由用户掌控。 ## 快速开始 选择你已经在使用的 agent。Codex 插件是实现完整主动与被动 memory 循环的最快捷径。 ### Codex 插件 ``` 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 hooks。 显式安装程序会下载最新发布的 paxm 二进制文件。该插件会注册 active-memory 技能，并在设置完成后接管被动的 Codex hooks； 它绝不会自行安装二进制文件、写入凭据或绕过 hook 信任。 在依赖被动 memory 之前，请验证首个成功的循环： ``` 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` 可实现可重现的版本或回滚。 Provider 凭据仍由用户管理。 ### Claude Code 插件 安装 paxm CLI，然后安装 Claude Code 插件： ``` 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 插件包含 active-memory 技能、paxm MCP server 和五个 生命周期 hook：`SessionStart`、`UserPromptSubmit`、`PostToolUse`、 `PostToolUseFailure` 和 `Stop`。 会话引导会注入配置好的用户、agent 和会话身份， 以及当前的本地时间和时区。Codex、Claude Code 和 Pi 使用它们的会话启动事件；OpenCode 在会话中发送第一条消息之前执行相同的引导。如果后续的用户输入距离上一次对话活动超过 12 小时，paxm 会在 agent 处理该输入之前刷新本地时间上下文。 ### OpenCode、Pi、CLI 或 MCP 安装最新版本并运行交互式设置。默认的 SQLite provider 让 adaptor 无需事先创建账户或 API key 即可使用。 ``` curl -fsSL https://github.com/pax-beehive/paxm/releases/latest/download/install.sh | bash paxm setup paxm config doctor ``` `paxm setup` 允许用户选择稳定的用户 ID、provider 和被动 agent 集成。选定的 agent 默认使用诸如 `codex-todd` 的 ID，并可以在交互式设置期间重命名。使用上/下键移动，空格键切换，回车键确认。 可选的团队 ID 会创建显式的持久化写入配置文件，例如 `team-pax-core`；非交互式设置可以传入 `--user-id todd --team-id pax-core`。 主动召回技能仍由用户安装。SQLite 无需 API key 即可工作；诸如 Zep、Mem0、MemOS 和 OpenViking 等远程 provider 则需要在设置期间提供连接详情。 必须允许 SQLite 健康检查在配置的数据库旁创建 WAL/SHM 文件。如果沙盒可以读取数据库但无法写入其父目录，可能会报告 SQLite 错误 14。 对于沙盒评估，请使用隔离的可写 SQLite 路径。在真实的 agent 进程中，相同的配置可能是健康的。 当 Codex 使用内置的 `paxm-memory` 插件时，请让该插件管理 Codex 的 hooks，这样 paxm 就不会注册重复的全局 hook： 写入并召回 memory： ``` paxm remember --profile ltm --text "We chose SQLite for the local memory layer" paxm recall --query "local memory layer" paxm history --days 7 paxm dashboard # localhost metrics, logs, sessions, and recall inspection ``` 在设置期间选择 OpenCode 可在 `~/.config/opencode/plugins/` 下安装全局本地插件。选择 Pi 则会安装其被动扩展。 选择 Cursor、TRAE、TRAE CN、Kimi Code、ZCode、Kiro 和 Cline 会安装客户端原生的 hook/MCP 集成，同时保留无关的客户端配置。 有关确切的事件映射、路径、主机限制、验证和回滚，请参阅 [agent 集成矩阵](docs/agent-integrations.md)。任何兼容 MCP 的 client 都可以使用 `paxm mcp serve --agent codex`；请将 `codex` 替换为已配置的 client 身份。 ## SQLite 质量预览 SQLite 让新用户在选择或部署专用 memory 系统之前，就能获得完整的本地 memory 循环。它使用 FTS5 和 BM25 检索，具有对话轮次级别的 memory 和确定性的、针对查询的摘要。Memory 摄取和检索不会调用任何外部 LLM 或 embedding 服务。 在最初的 30 个问题 LoCoMo agent 评估中，SQLite turn memory 成功回答了 13 个问题，相比之下 Mem0 product-default 回答了 11 个。 | Memory 组别 | 成功回答数 | 平均 token F1 | memory 层中的外部模型 | | --- | ---: | ---: | --- | | paxm SQLite turn memory | 13 / 30 | 0.4211 | 无 | | Mem0 product-default | 11 / 30 | 0.3811 | GPT-5 mini + OpenAI embeddings | 这是一个探索性结果，并非官方的 LoCoMo 得分，也不能证明 SQLite 在整体上优于 Mem0。它涵盖了使用 OpenCode 和 DeepSeek V4 Flash 的一次平衡对话，并使用了确定性的 token F1。请参阅[方法论与局限性](evals/locomo/README.md)。 ## 工作原理  PAXM 是一个 memory adaptor，而不是另一个托管的 memory 服务： ``` AI agents -> CLI / MCP / skills / hooks -> paxm -> any memory provider ``` Agent 通过两种方式访问 paxm： | 路径 | 入口点 | 最适用于 | | --- | --- | --- | | 主动 | CLI、MCP、skill | 刻意召回、显式写入、检查 | | 被动 | Agent 生命周期 hook | Prompt 阶段召回和自动对话轮次捕获 | 两条路径都使用相同的 runtime 和 provider 路由。在所有 agent 界面中，过滤、配置文件、排名、超时、遥测和 provider 行为保持一致。 被动写入在 provider 交付之前提交到本地持久化队列。缓慢或不可用的 provider 会在后台重试，而不是阻塞 agent。 被动召回默认使用 `800ms` 的总体预算和每个 provider `250ms` 的预算。它会返回健康的部分结果并记录下游超时。 ### 运行示意

一个 agent 界面，适配任何 memory provider

PAXM 保持了面向 agent 的契约稳定，同时配置文件会选择 provider、失败策略、排名和超时。SQLite 是零配置的默认选项，而不是必需的存储后端。

被动召回和持久化的后台写入

生命周期 hook 在模型请求之前召回上下文，并在之后捕获已完成的对话轮次。写入在 provider 交付之前进入持久化的本地队列，因此 provider 延迟不会阻塞 agent。

阅读详细的[架构](docs/architecture.md)和 [provider adaptor 契约](docs/provider-adapter-contract.md)。 存储的 memory 将其 `origin`（用户、agent、会话和对话轮次）与其可见性 `scope` 区分开来。声明支持归因的 provider 必须往返这两个值；请参阅 [JSON-RPC provider 协议](docs/jsonrpc-provider-protocol.md#origin-scope-and-trust)。 ## Agent 与 provider ### Agent 界面 | Agent/client | 主动 | 被动召回 | 被动写入 | | --- | :---: | :---: | :---: | | Codex | CLI、MCP、skill | Hook | Hook | | Claude Code | CLI、MCP、skill | Hook | Hook | | Pi | CLI、MCP、skill | Extension | Extension | | OpenCode | CLI、MCP | Plugin | Plugin | | Cursor | MCP | — | Hook | | TRAE / TRAE CN | MCP | Hook | Hook | | Kimi Code | MCP | Hook | Hook | | ZCode | MCP | Hook | Hook | | Kiro `paxm` agent | MCP | Hook | Hook | | Cline | MCP | Hook | Hook | | 任何 MCP client | MCP tools | — | — | ### Memory provider | Provider | 模式 | 备注 | | --- | --- | --- | | SQLite | 默认，内置 | 零配置的 turn memory；无需 API key、LLM 或 embeddings | | Zep | 内置 | 用户或图谱范围 | | Mem0 | 内置 | 自托管 REST API | | Mem0 Cloud | 内置 | 托管平台 API，支持异步 v3 写入/搜索 | | MemOS | 内置 | 自托管产品 API，按 memory cube 划分范围 | | MemOS Cloud | 内置 | 托管 OpenMem API，使用 Token 身份验证 | | OpenViking | 内置 | 自托管会话提取和语义 memory 搜索 | | 自定义 JSON-RPC | Adapter | 引入现有或私有的 memory 系统 | 支持一次启用多个 provider 实例。召回和写入配置文件控制路由、必需或尽力而为的行为、排名权重、阈值、memory 层级和超时。 Mem0 分数的方向取决于具体部署。出于向后兼容性，`score_semantics` 默认为 `similarity`；当 Mem0 endpoint 返回 pgvector 余弦距离时，请将其设置为 `distance`。Paxm 无法从名为 `score` 或 `similarity` 的字段中推断出这一点。 自托管 Mem0 的搜索范围放置也依赖于版本。`search_scope_payload: auto` 会首先在 `filters` 内部发送 `user_id`、`agent_id` 和 `run_id`，然后在服务器返回已知的缺失范围兼容性错误时，仅使用顶层字段重试一次。对于 Mem0 0.1.117 风格的服务器请设置 `top_level`，对于严格的嵌套过滤器部署请设置 `filters`。 ### 自托管 OpenViking 运行 `paxm setup`，选择 OpenViking，并提供自托管的 base URL 和 API key。随后 OpenViking 即可参与与 SQLite 或任何其他 provider 相同的召回和写入配置文件，并支持必需或尽力而为的路由以及特定于 provider 的超时。 ## MCP server 将 paxm 作为本地 stdio MCP server 运行： ``` paxm mcp serve --agent codex ``` ``` { "command": "paxm", "args": ["mcp", "serve", "--agent", "codex"] } ``` 该 server 暴露了四个专注的工具： - `paxm_recall` - `paxm_remember` - `paxm_history` - `paxm_config_doctor` 设置、凭据管理、hook 安装和数据回填保留在 MCP 之外，因此 agent 无法悄悄获取用户配置的所有权。 写入携带用户、agent 以及命名的个人/团队 scope 来源。召回不会根据该 scope 进行过滤：CLI、MCP 和被动注入会为每个结果标记其源 scope，而 provider 原生的路由和 ACL 仍由 provider 控制。 ## Agent 集成 ### Codex 插件 Codex 插件打包了 paxm 设置技能、active memory 技能和原生的 Codex hooks。它不会安装 provider 凭据或绕过 hook 信任。 使用 `paxm setup --integration codex-plugin`，以便只有该插件管理 Codex 生命周期 hooks。 ### Claude Code 插件 Claude Code 插件是一等集成，而不是通用的 setup shim。它打包了技能、 MCP server 和五个原生生命周期 hook。 Setup 仅移除旧版由 paxm 管理的 Claude hooks，保留无关的 hooks，并记录 `claude-plugin` 的所有权。 ### Pi extension ### OpenCode 插件 生成的插件位于 `~/.config/opencode/plugins/paxm.ts`，或者在配置后位于 `OPENCODE_CONFIG_DIR`/`XDG_CONFIG_HOME` 下方。 有关生成的 paths、事件映射、配置文件设置和卸载行为，请参阅完整的[配置指南](docs/config.md)。 ## 默认可靠性 - Hook 确认仅等待本地队列事务。 - Provider 交付是可恢复的，并在后台进行重试。 - 可选的 provider 失败不会丢弃健康 provider 的结果。 - 卡住的 provider 受其超时和单次调用舱壁限制。 - 写入 provider 路由默认有 30 秒的超时；可选的失败保持隔离，而必需 provider 的失败会返回给调用者。 - 召回来源会在被动写入之前被剔除，以防止 memory 回声。 - 严格的 LTM 整合限制了重复累积。 - SQLite 使用明确的会话、轮次和时间边界保存已完成的 agent 对话轮次。 - 遥测默认存储哈希和长度，而不是原始召回查询。 历史导入也是可恢复的： ``` 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 ``` ## 性能 基准测试使用模拟真实被动 agent 工作负载的运行时生成临时数据集；仓库中未提交任何基准语料库。 在 Apple M4 参考机器上： | 工作负载 | Adapter 延迟 | | --- | ---: | | 128 KiB SQLite 写入 | 1.84 ms | | 2 MiB SQLite 写入 | 14.31 ms | | 10 项 / 1.25 MiB 批次 | 12.36 ms | | 从 100,000 条短 memory 中召回 | 0.54 ms | | 从 10,000 条 x 32 KiB 的 memory 中召回 | 0.61 ms | 这些数字衡量的是 adaptor，而不是端到端的 agent 响应时间。请在 [SQLite adaptor 基准测试](docs/benchmarks.md)中查看数据集、命令、分配和机器详情。 ## 评估 paxm 将确定性回归套件与付费的真实 agent 质量评估分离开来。CI 保护运行时行为；可选的基准测试则衡量 memory 是否有助于 agent 正确回答。 该仓库包含确定性的生产路径评估： ``` go run ./cmd/paxm eval run --suite evals/baseline go run ./cmd/paxm eval run --suite evals/conversation-write ``` - 100 个用例的检索套件会报告 recall@K、precision@K、MRR、假阳性率、延迟以及类别级别的结果。 - 50 个用例的对话转写入套件会检查准入、召回、禁止片段、元数据保留以及 adaptor 契约行为。 CI 在每次推送到 `main` 和每个 pull request 时运行单元测试、vet、检索报告和 adaptor 写入契约。 可选的 [LoCoMo agent 基准测试](evals/locomo/README.md)会运行真实的 OpenCode 会话以及生产环境的 MCP 或被动召回。 [跨 agent 基准测试](evals/cross-agent/README.md)测试了一个 agent 的经验是否有助于另一个 agent 避免同样的失败。 付费的 agent 评估绝不会在普通的 CI 中运行。它们的报告将 memory 层成本与回答模型成本区分开来，并声明其证据限制。 ## 文档 | 指南 | 内容 | | --- | --- | | [中文使用指南](docs/README.zh-CN.md) | 中文快速开始、agent 接入、provider 配置与排障 | | [中文 JSON-RPC 接入指南](docs/jsonrpc-provider-protocol.zh-CN.md) | 自定义 memory provider 的协议、实现与一致性验证 | | [配置](docs/config.md) | Provider、配置文件、agent、hook、遥测 | | [架构](docs/architecture.md) | Runtime 模块和数据流 | | [Provider 契约](docs/provider-adapter-contract.md) | 实现 memory adaptor | | [基准测试](docs/benchmarks.md) | 被动工作负载数据集和结果 | | [LoCoMo 评估](evals/locomo/README.md) | 真实 agent 的 memory 质量方法论 | | [发布指南](docs/release.md) | 构建、校验和、标签和发布 | | [路线图](docs/roadmap.md) | 当前产品方向 | ## 开发 ``` 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)。

标签：AI编程助手, EVTX分析, Go, MCP, Ruby工具, SOC Prime, SQLite, 上下文管理, 开发工具, 日志审计, 记忆存储