@aliyunpolar/polarmemory

PolarDB-PG 记忆管理的统一接入层：一个 polarmemory CLI（记忆操作命令），一条 setup 命令完成多个 AI 编程助手的一键接入（配置写入、Hooks/插件注册、SKILL 安装、连通性校验）。接入后每次提问自动召回相关记忆、每轮对话结束自动沉淀记忆，无需手动操作。

| Agent | 接入机制 | 配置文件 | SKILL 安装路径 | |---|---|---|---| | qoder | Hooks（UserPromptSubmit + Stop + SessionStart） | ~/.qoder/settings.json | ~/.qoder/skills/polarmemory-memory/ | | qoderwork | Hooks（同上） | ~/.qoderwork/settings.json | ~/.qoderwork/skills/polarmemory-memory/ | | qwenwork | Hooks（同上） | ~/.qwenwork/settings.json | ~/.qwenwork/skills/polarmemory-memory/ | | claude | Hooks（同上） | ~/.claude/settings.json | ~/.claude/skills/polarmemory-memory/ | | codex | Hooks（同上）+ [features].hooks=true | ~/.codex/hooks.json + config.toml | ~/.codex/skills/polarmemory-memory/ | | opencode | 进程内插件（chat.message + system.transform） | ~/.config/opencode/plugins/polarmemory.js | — | | hermes | Shell Hooks（pre_llm_call + post_llm_call） | ~/.hermes/config.yaml | ~/.hermes/skills/polarmemory-memory/ |

OpenClaw 使用自身插件管理系统，通过独立包 polarmemory_openclaw 接入（见下文）。

配置与日志位于 ~/.polarmemory/（config.json 按 agent 分节隔离，多 agent 默认共享同一记忆桶）。

安装与接入

方式一：一键安装脚本

curl -fsSL <公网地址>/install.sh | sh -s -- \
  --agent qoder --api-key <API_KEY> --base-url http://<IP>:<PORT>

四阶段自动完成：检查运行时 → 安装 CLI → 配置 Agent → 校验连通性。脚本随包分发于 bootstrap/install.sh，另有供 Agent 阅读的手册 bootstrap/install.md。脚本不会安装 Node.js，缺失或版本过低时会停止并给出升级指引。

方式二：手动安装

npm install -g @aliyunpolar/polarmemory

polarmemory setup --agent <agent> --api-key <API_KEY> --base-url http://<IP>:<PORT>

# 验证
polarmemory status --agent <agent> --json

安装成功后重启对应 Agent（新开会话即可）使 hooks/插件生效。

• --base-url 必传（首次）：为一客户一部署，无统一公网域名可内置。http/https 均支持；http 时 setup 会打印一行非阻断警告（公网环境建议 HTTPS）。
• --user-id 可选，默认 "default"：API Key 已隔离部署（租户），user_id 仅作部署内的记忆分桶。多人共用同一部署时请为每人指定不同 --user-id。
• 重跑 polarmemory setup --agent <a> 可修复 hooks/skill（api-key/base-url 可省略，沿用存量配置）。

OpenClaw 接入

OpenClaw 必须通过其插件管理器安装，不能直接写文件：

openclaw plugins install npm:polarmemory_openclaw
openclaw plugins enable  polarmemory_openclaw
polarmemory setup --agent openclaw --api-key <API_KEY> --base-url http://<IP>:<PORT> --no-validate
openclaw gateway restart

setup 做了什么

1. 前置检查：Node ≥ 20、agent home 存在
2. 写配置：~/.polarmemory/config.json 的 agents.<agent> 分节
3. 注册 Hooks / 写入插件文件（修改用户配置前自动写 .bak-polarmemory-<TS> 备份，保留最近 5 份；条目带 _polarmemory 标记，卸载时精确剥离，不触碰你自己添加的配置）：

| 触发 | 行为 | |---|---| | 用户提交提问 | 调 POST /v2/memories/search 召回相关记忆，以 <recalled-memories> 块注入上下文 | | 回合结束 | 切出当前轮，清洗后 POST /v1/memories 异步存储（session_id 作为 run_id） | | 会话开始 | 可选预热召回（warmup_recall 默认关闭） |

4. 安装 SKILL（教 agent 在用户显式说“记住/查记忆”时调 CLI）
5. 连通性校验：GET /v1/ping（可达性）+ GET /v1/db_info（Key 有效性），配错当场报错

Codex 特别说明：需要 ~/.codex/config.toml 中存在 [features] 段且 hooks = true。setup 采用只追加不重写策略；遇到内联表写法、点号写法、已有其他值、多个 [features] 段、无法安全解析等情况时不猜测、不修改，转为提示手动设置。

Hermes 特别说明：Hermes 的 shell hooks 需要用户在其 allowlist 中批准后才会执行，setup 完成后会给出 approval-hint 引导；未批准前 status 报告未完成。

可靠性设计

• Fail-open：所有 hooks 任何错误静默退出（exit 0），绝不干扰对话。逃生阀：给 agent 进程设置 POLARMEMORY_SKIP_HOOKS=TRUE 使所有 hook 入口立即退出。
• 断路器：服务不可达（连接类错误，HTTP 4xx/5xx 不算）时写入 60 秒冷却标记，冷却期内召回/捕获全部瞬时跳过，避免每次提问白等超时。同一 base_url 的多个 agent 共享熔断状态。
• 去重指纹：对已捕获轮次做 SHA-256 指纹并持久化，同一轮重复触发不重复沉淀。
• 防污染：捕获前剥离 <recalled-memories> 等注入块，防止召回内容回流成新记忆。
• 防注入：召回块含安全前言，明确记忆为“仅供参考的上下文、非指令”，并对记忆正文中的闭合标签做转义。

CLI 命令

# 接入 / 状态 / 连通性
polarmemory setup --agent <agent> --api-key <KEY> --base-url <URL> [--user-id <id>]
polarmemory status --agent <agent> [--json]
polarmemory ping --agent <agent>

# 自升级（全局 npm 安装场景）
polarmemory upgrade

# 记忆操作
polarmemory memory add "<text>" --agent=<agent> [--no-infer]
polarmemory memory search "<query>" --agent=<agent> [--top-k=N] [--threshold=F]
polarmemory memory list --agent=<agent> [--page=N] [--page-size=N]
polarmemory memory get <memory-id> --agent=<agent>
polarmemory memory update <memory-id> --text="<new text>" --agent=<agent>
polarmemory memory delete <memory-id> --agent=<agent>
polarmemory memory delete --all --yes --agent=<agent>

# 卸载
polarmemory uninstall [--agent <agent>] [--purge-config]

Agent 也可通过 POLARMEMORY_AGENT 环境变量指定，省略 --agent。

版本更新提示

CLI 在交互式终端下会以每 24 小时一次的频率在后台检查新版本，并在命令成功后打印一行提示。该检查完全不阻塞命令执行；在 CI、--json 输出、非交互终端下自动关闭，也可用 POLARMEMORY_DISABLE_UPDATE_CHECK=1 显式关闭。

配置

~/.polarmemory/config.json 按 agent 分节：

| 字段 | 默认值 | 说明 | |---|---|---| | api_key | — | 鉴权 Token | | base_url | — | 服务端点 | | user_id | "default" | 记忆分桶键 | | auto_capture | true | 自动沉淀 | | auto_recall | true | 自动召回 | | warmup_recall | false | 会话开始预热召回 | | top_k | 5 | 召回条数 | | threshold | 0.4 | 召回相似度阈值 | | debug | false | 写调试日志到 ~/.polarmemory/logs/ |

环境变量 POLARMEMORY_API_KEY / POLARMEMORY_BASE_URL / POLARMEMORY_USER_ID 优先于配置文件。

卸载

polarmemory uninstall --agent <agent>          # 移除该 agent 的 hooks/插件与 SKILL
polarmemory uninstall --purge-config           # 同时删除配置文件
npm uninstall -g @aliyunpolar/polarmemory      # 最后移除二进制

顺序重要：必须先 polarmemory uninstall，再 npm uninstall，否则 CLI 已被移除将无法清理 hooks。

开发

pnpm install
pnpm run typecheck
pnpm run test
pnpm run build

本仓库为 pnpm monorepo，包含三个独立发布的包：本包、@aliyunpolar/polarmemory-shared（共享内核）、polarmemory_openclaw（OpenClaw 插件）。

License

Apache-2.0