@aliyunpolar/polarmem0

polarmem0 记忆服务的统一接入层：一个 polarmem0 CLI（记忆操作命令），一条 setup 命令完成 Qoder / QoderWork 的一键接入（配置写入、Hooks 注册、SKILL 安装、连通性校验）。

| Agent | Hooks | Skill 安装路径 | 形态 | |---|---|---|---| | qoder | ✅ UserPromptSubmit + Stop + SessionStart | ~/.qoder/skills/polarmem0-memory/ | hooks 驱动（自动捕获/召回） | | qoderwork | ✅ UserPromptSubmit + Stop + SessionStart | ~/.qoderwork/skills/polarmem0-memory/ | hooks 驱动（自动捕获/召回） |

配置与日志位于 ~/.polarmem0/（config.json 按 agent 分节隔离）。

安装与接入

npm install -g @aliyunpolar/polarmem0

# 一键接入（接入命令由交付文档/控制台预填生成，替换 <API_KEY> 与端点）
polarmem0 setup --agent qoder --api-key <API_KEY> --base-url http://<IP>:<PORT>
polarmem0 setup --agent qoderwork --api-key <API_KEY> --base-url http://<IP>:<PORT>

# 验证
polarmem0 status --agent qoder --json

安装成功后重启 Qoder / QoderWork（新开会话即可）使 hooks 生效。

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

setup 做了什么

1. 前置检查：Node ≥ 20、agent home 存在（~/.qoder 或 ~/.qoder-cn；qoderwork 同理）
2. 写配置：~/.polarmem0/config.json 的 agents.<agent> 分节
3. 注册 Hooks 到 ~/.qoder{work}/settings.json（修改前自动写 settings.json.bak-polarmem0-<TS> 备份，保留最近 5 份；条目带 _polarmem0 标记，卸载时精确剥离，不触碰你自己添加的 hooks）：

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

4. 安装 SKILL 到 ~/.qoder{work}/skills/polarmem0-memory/（教 agent 在用户显式说"记住/查记忆"时调 CLI）
5. 连通性校验：GET /v1/ping（可达性）+ GET /v1/db_info（Key 有效性），配错当场报错

所有 hooks 严格 fail-open：任何错误静默退出（exit 0），绝不干扰对话。逃生阀：给 agent 进程设置 POLARMEM0_SKIP_HOOKS=TRUE 可使所有 hook 入口立即退出。

CLI 命令

polarmem0 memory add "<text>" --agent=qoder [--no-infer]   # 存记忆（--no-infer 原文存储，跳过 LLM 事实抽取）
polarmem0 memory search "<query>" --agent=qoder [--top-k=N] [--threshold=F]
polarmem0 memory list --agent=qoder [--page=N] [--page-size=N]
polarmem0 memory get <memory-id> --agent=qoder
polarmem0 memory update <memory-id> --text="<new>" --agent=qoder
polarmem0 memory delete <memory-id> --agent=qoder
polarmem0 memory delete --all --yes --agent=qoder          # 清空当前 user 桶（需 --yes 确认）
polarmem0 ping --agent=qoder
polarmem0 status --agent=qoder --json

Agent 选择：--agent 参数，否则 POLARMEM0_AGENT 环境变量。

配置

~/.polarmem0/config.json：

{
  "version": 1,
  "agents": {
    "qoder": {
      "api_key": "...",
      "base_url": "http://<IP>:<PORT>",
      "user_id": "default",
      "auto_capture": true,
      "auto_recall": true,
      "warmup_recall": false,
      "top_k": 5,
      "threshold": 0.4,
      "debug": false
    }
  }
}

| 字段 | 默认 | 含义 | |---|---|---| | user_id | "default" | 每次捕获/召回的记忆分桶键 | | auto_capture | true | 回合结束自动捕获记忆 | | auto_recall | true | 提问时自动召回记忆 | | warmup_recall | false | 会话开始时按 cwd 预热召回 | | top_k / threshold | 5 / 0.4 | 召回条数与相似度下限 | | debug | false | hook 详细日志（~/.polarmem0/logs/polarmem0.log） |

环境变量覆盖（env 优先）：POLARMEM0_AGENT / POLARMEM0_API_KEY / POLARMEM0_BASE_URL / POLARMEM0_USER_ID；测试用 POLARMEM0_HOME 可重定向全部落盘路径。

卸载

⚠️ 顺序很重要：先 polarmem0 uninstall，再 npm uninstall -g。反过来会留下指向已删除脚本的 hook 条目。

polarmem0 uninstall --agent qoder     # 单 agent：剥离 hooks（带备份）+ 删 skill + 删配置分节
polarmem0 uninstall                   # 所有 agent
polarmem0 uninstall --purge-config    # 同时删除 ~/.polarmem0/config.json
npm uninstall -g @aliyunpolar/polarmem0

开发

pnpm install
pnpm run build        # tsup + 拷贝 skill 资产
pnpm run test         # vitest
pnpm run lint         # biome
pnpm run typecheck    # tsc --noEmit

老 glibc 开发机（如 CentOS 7）上 vitest 依赖的 rollup 原生二进制不可用，pnpm-workspace.yaml 已内置 wasm override，无需额外处理。

License

Apache-2.0