# pi-agent-memory-tencentdb

**Repository Path**: fanshuangstrive/pi-agent-memory-tencentdb

## Basic Information

- **Project Name**: pi-agent-memory-tencentdb
- **Description**: No description available
- **Primary Language**: TypeScript
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-08-13
- **Last Updated**: 2026-08-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Pi Agent Memory × TencentDB（中文）

> 英文文档见 [README.md](README.md)。

Pi coding-agent 扩展，将 Pi 连接到 [TencentDB Agent Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)（MemoryCore）Gateway，为 Pi 用户提供**团队级、跨框架的持久化记忆**。

## 功能

- **`memory_recall`** — 按查询召回相关的团队记忆（事实、决策、偏好）
- **`memory_capture`** — 显式保存一条持久事实/决策到团队记忆
- **`memory_search`** — 全文检索历史团队对话（L0）
- **自动捕获** — 完成的 agent 轮次在 `agent_end` 时写入 L0
- **自动注入** — 召回的记忆在 `before_agent_start` 时追加到系统提示词（冻结快照，保留 prompt 缓存）

## 前置条件

1. **Node.js >= 22**（Pi 运行时和 MemoryCore 都要求）。
2. 一个运行中的 **MemoryCore Gateway**（[TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)，单节点 standalone 即可）：
   ```bash
   git clone https://github.com/TencentCloud/TencentDB-Agent-Memory
   cd TencentDB-Agent-Memory
   npm install --ignore-scripts
   export TDAI_GATEWAY_CONFIG="$PWD/tdai-gateway.standalone.yaml"
   export TDAI_LLM_API_KEY="your-api-key"
   export TDAI_LLM_BASE_URL="https://api.openai.com/v1"
   export TDAI_LLM_MODEL="gpt-4o-mini"
   node --import tsx src/gateway/server.ts
   ```
   Gateway 默认监听 `http://127.0.0.1:8420`。验证方式：
   ```bash
   curl -s http://127.0.0.1:8420/health   # → { "status": "ok", "version": "2.0.1", ... }
   ```
3. **Team / Agent（可选）。** v3 数据面按 `team + agent + user` 三元组隔离数据。如果配置中省略 `teamId` / `agentId` / `userId`，Gateway 会回退到共享的 `default` 桶——单用户试用足够。需要按团队隔离时，通过 v3 meta API 创建显式的 Team/Agent id（见 MemoryCore 仓库文档）。

### 使用自托管 / 兼容 OpenAI 的 LLM 端点

MemoryCore 的记忆蒸馏（L0→L3）和 Skill 提取依赖一个 OpenAI 兼容的 LLM API。可配置任意 OpenAI 兼容端点（自托管或第三方）作为 `TDAI_LLM_*`：

```bash
export TDAI_LLM_BASE_URL="<your-openai-compatible-base-url>"
export TDAI_LLM_API_KEY="<your-api-key>"
export TDAI_LLM_MODEL="DeepSeek-V4-Flash"   # 或 MiniMax-M3
```

该端点（`openai-completions` 协议）提供两个模型：

| 模型 | 上下文窗口 | 最大输出 | 推理 | 输入 |
|------|-----------|---------|------|------|
| **MiniMax-M3 多模态** | 204,800 | 32,768 | ✅ | text + image |
| **DeepSeek-V4-Flash** | 204,800 | 32,768 | ✅ | text |

> 提示：`DeepSeek-V4-Flash` 适合纯文本记忆提取（更快、更省）；`MiniMax-M3` 支持多模态，适合需要图片理解的场景。两者都支持推理（reasoning），可提升记忆蒸馏质量。

## 安装

```bash
pi install git:github.com/fanshuangstrive/pi-agent-memory-tencentdb
```

> 该包尚未发布到 npm。发布后 `pi install npm:pi-agent-memory-tencentdb` 也可用。

## 快速上手（端到端）

1. 启动 MemoryCore Gateway（见前置条件），确认 `/health` 返回 `ok`。
2. 安装扩展：`pi install git:github.com/fanshuangstrive/pi-agent-memory-tencentdb`
3. 创建 `~/.pi/agent/pi-agent-memory-tencentdb.json`（最小配置，单用户）：
   ```json
   {
     "endpoint": "http://127.0.0.1:8420",
     "serviceId": "default"
   }
   ```
4. 重启 Pi（或 `/reload`），然后运行 `/memory-status` —— 显示 `gateway: reachable (v2.0.1)` 表示适配器已接通。
5. 向 Pi 提问，然后让它记住一个事实：
   > "记住：我们的 API 所有 JSON 字段都用 snake_case。"

   Pi 会调用 `memory_capture`；该事实存入 L0，之后由 Gateway 流水线蒸馏为可召回的记忆。
6. 在**新**会话中问一个相关问题（例如"我们的 API 字段命名规范是什么？"）。自动注入步骤会召回已存事实并追加到系统提示词，Pi 即可基于团队记忆回答。

## 开发

这是一个独立的扩展项目（不属于 Pi monorepo）。扩展由 Pi 通过 jiti 在运行时加载，因此 `pi install` 无需构建步骤。

```bash
npm install --ignore-scripts
npm run check   # tsc --noEmit
npm run lint    # biome check src/ test/
npm test        # node:test via tsx
```

要求 Node.js >= 22。

## 配置

创建 `~/.pi/agent/pi-agent-memory-tencentdb.json`（可用 `PI_TENCENTDB_CONFIG` 覆盖路径）。文件不存在表示"全部使用默认值"——适配器仍可对接本地 Gateway。

```json
{
  "endpoint": "http://127.0.0.1:8420",
  "apiKey": "sk-...",
  "serviceId": "default",
  "teamId": "t_1",
  "agentId": "agt_1",
  "userId": "u_1",
  "captureEnabled": true,
  "injectEnabled": true,
  "maxRecall": 5,
  "maxRecallChars": 4000,
  "requestTimeoutMs": 5000,
  "maxRetries": 3,
  "retryBaseDelayMs": 100,
  "recallThreshold": 0.5,
  "recallMode": "hybrid"
}
```

| 字段 | 必填 | 默认值 | 说明 |
|-------|------|--------|------|
| `endpoint` | 否 | `http://127.0.0.1:8420` | MemoryCore Gateway 基础 URL。 |
| `apiKey` | 否 | — | Bearer token。Gateway 绑定非回环地址或启用鉴权时必填；回环且关闭鉴权时任意值（或不填）均可。也可用环境变量 `PI_TENCENTDB_API_KEY` 提供（环境变量优先于配置文件，密钥无需落盘）。 |
| `serviceId` | 否 | `default` | 记忆实例 id（`x-tdai-service-id`）。 |
| `teamId` | 否 | — | v3 隔离用的团队 id。省略则使用共享的 `default` 桶。 |
| `agentId` | 否 | — | v3 隔离用的 agent id。与 `teamId` 同时设置时必须属于该团队。 |
| `userId` | 否 | — | v3 隔离用的终端用户 id（使用 Pi 的人，非 MemoryCore 概念）。 |
| `sessionId` | 否 | 自动 | 稳定的 L0 会话 id。省略时每次捕获自动生成。 |
| `captureEnabled` | 否 | `true` | 在 `agent_end` 时将完成的轮次写入 L0。 |
| `injectEnabled` | 否 | `true` | 在 `before_agent_start` 时将召回记忆注入系统提示词。 |
| `maxRecall` | 否 | `5` | 每轮注入的最大召回条数。 |
| `maxRecallChars` | 否 | `4000` | 注入块的字符预算（按条目边界截断）。 |
| `llmModel` | 否 | — | 记忆提取用的 LLM 模型（回退到 Gateway 默认）。 |
| `requestTimeoutMs` | 否 | `5000` | 单请求超时；Gateway 挂起不会阻塞 agent 循环。 |
| `maxRetries` | 否 | `3` | Gateway 瞬时故障（网络错误、5xx、429）的重试次数。逻辑失败（envelope `code` 非零）永不重试。 |
| `retryBaseDelayMs` | 否 | `100` | 指数退避基础延迟：`base × 2^attempt`（100 ms、200 ms、400 ms）。 |
| `recallThreshold` | 否 | `0.5` | 传给 `/v3/atomic/search` 的相似度阈值（0..1）。 |
| `recallMode` | 否 | `hybrid` | 传给 Gateway 的检索模式：`hybrid`（BM25 + 向量）、`vector` 或 `bm25`。 |

非法值（类型错误、超出范围）和未知字段会报告到 stderr 并替换为默认值——适配器绝不会因坏配置崩溃。

### 瞬时故障重试

Gateway 调用遇到网络错误、HTTP 5xx 或 429 时，按指数退避（`retryBaseDelayMs × 2^attempt`）最多重试 `maxRetries` 次。逻辑失败（v3 envelope `code` 非零，例如 `team not found`）和鉴权失败（401/403）**不会**重试——它们不会自行恢复。

## 命令

- `/memory-status` — 显示适配器状态和配置。输出字段：
  - `endpoint` — 配置中的 Gateway 基础 URL。
  - `serviceId` / `teamId` / `agentId` — 当前使用的 v3 身份三元组（省略时显示 `(unset)`）。
  - `capture` / `inject` — 自动捕获和自动注入是否开启。
  - `gateway` — `/health` 返回 `ok` 时显示 `reachable (v<version>)`，否则 `UNREACHABLE`。
- `/memory-list [l1|l0] [--limit N]` — 列出已存的 L1 记忆或最近的 L0 对话。
- `/memory-export [path] [--limit N]` — 将 L1 + L0 导出为 JSON 文件。
- 会话级开关（仅覆盖当前会话，不改配置文件）：
  - `/memory-capture-on` / `/memory-capture-off` — 开启/关闭 L0 捕获。
  - `/memory-inject-on` / `/memory-inject-off` — 开启/关闭提示词注入。

### 命令如何注册

Pi 启动时通过 jiti 加载扩展（无需构建），调用入口 `src/index.ts` 的默认导出函数，并传入 `ExtensionAPI` 对象。扩展在函数内对每个命令调用：

```ts
pi.registerCommand("memory-status", {
  description: "Show TencentDB agent-memory adapter status and config",
  handler: async (args, ctx) => { /* 返回要显示给用户的文本 */ },
});
```

Pi 会自动加上 `/` 前缀：TUI 中输入 `/` 时列出所有已注册命令供补全，回车后 Pi 调用对应的 `handler(args, ctx)`，返回值显示在 TUI 中。三个工具（`memory_recall` / `memory_capture` / `memory_search`）通过 `pi.registerTool` 以同样方式注册，但由 LLM 在对话中调用，而非用户手动输入。

## 架构

```mermaid
flowchart TD
    subgraph Pi["Pi coding-agent"]
        A["before_agent_start<br/>召回 → 注入（冻结快照）"]
        B["agent_end<br/>捕获轮次 → L0"]
        C["工具<br/>memory_recall / memory_capture / memory_search"]
    end
    subgraph GW["MemoryCore Gateway :8420"]
        D["/v3/conversation/*  (L0)"]
        E["/v3/atomic/*  (L1)"]
        F["/v3/scenario/*  (L2)"]
        G["/v3/core/*  (L3)"]
        H["流水线 worker<br/>L0 → L1/L2/L3 蒸馏"]
    end
    A -->|POST /v3/atomic/search| E
    B -->|POST /v3/conversation/add| D
    C -->|/v3/*| D
    C -->|/v3/*| E
    D --> H
    H --> E
    H --> F
    H --> G
```

所有请求都携带 `Authorization: Bearer <apiKey>` 以及 `x-tdai-service-id` / `x-tdai-team-id` / `x-tdai-agent-id` / `x-tdai-user-id` 身份头。

## 故障排查

| 现象 | 可能原因 | 解决办法 |
|------|----------|----------|
| `/memory-status` 显示 `gateway: UNREACHABLE` | Gateway 未运行、`endpoint` 或端口错误 | 启动 Gateway；确认 `curl <endpoint>/health` 返回 `{"status":"ok"}`。 |
| `gateway: reachable` 但工具报错 | 鉴权或身份不匹配 | 检查 `apiKey`（非回环需要真实 token）以及 `teamId`/`agentId` 是否构成有效组合。 |
| 记忆已捕获但召回不到 | L0→L1 蒸馏是异步的 | Gateway 流水线每隔几轮对话提取一次记忆；刚保存的事实可能还召回不到。 |
| 提示词中没有注入记忆 | `injectEnabled` 为 `false`，或没有召回到相关内容 | 开启 `injectEnabled`；召回是查询驱动的——新话题可能合理地返回 0 条。 |
| Pi 启动时有配置警告 | JSON 中字段类型错误或未知键 | 阅读 stderr 警告；该字段已被替换为默认值。修正 JSON 后重启。 |
| Gateway 挂起卡住 agent | （不应发生） | 请求受 `requestTimeoutMs`（默认 5000 ms）约束，且所有失败都是非致命的。 |

## 用 Docker 运行 Gateway（可选）

MemoryCore 不提供官方 Gateway 镜像，推荐从源码运行（见前置条件）。如果偏好容器，可从 MemoryCore 源码树构建。这是社区示例，非官方产物：

`Dockerfile.gateway`（放在 MemoryCore 仓库根目录）：

```dockerfile
FROM node:22-slim
WORKDIR /app
COPY . .
RUN npm install --ignore-scripts
ENV TDAI_GATEWAY_CONFIG=/app/tdai-gateway.standalone.yaml
EXPOSE 8420
CMD ["node", "--import", "tsx", "src/gateway/server.ts"]
```

`docker-compose.yml`：

```yaml
services:
  memorycore-gateway:
    build:
      context: ./TencentDB-Agent-Memory
      dockerfile: Dockerfile.gateway
    ports:
      - "8420:8420"
    environment:
      TDAI_LLM_API_KEY: ${TDAI_LLM_API_KEY}
      TDAI_LLM_BASE_URL: ${TDAI_LLM_BASE_URL:-https://api.openai.com/v1}
      TDAI_LLM_MODEL: ${TDAI_LLM_MODEL:-gpt-4o-mini}
    restart: unless-stopped
```

然后将扩展的 `endpoint` 指向容器（例如 `http://127.0.0.1:8420`）。

## 贡献

开发环境、代码规范和 PR 流程见 [CONTRIBUTING.md](CONTRIBUTING.md)。所有提交必须按 [Developer Certificate of Origin](.github/DCO) 签署（`git commit -s`）。

## 备注

- **外部依赖**：需要一个运行中的 MemoryCore Gateway + 一个 OpenAI 兼容 LLM API 用于记忆提取。
- **许可证**：MemoryCore 为 MIT；本适配器为 MIT。
- **共存**：可与 `pi-hermes-memory`（单机个人记忆）同时运行——本适配器负责团队/共享记忆。