AnalyticDB for PostgreSQL 长记忆 Skills 对接 Qoder

环境识别与配置加载

当用户在 AI IDE 的对话中触发某个 Skill 时，Skill 首先通过环境变量自动识别当前 IDE 类型（QODER_AGENT 或 VSCODE_BRAND 标识 Qoder 环境）。识别完成后，Skill 从对应的 IDE 配置目录（.qoder/）中读取 adbpgmem.conf 配置文件，获取 API 地址、认证令牌和用户标识。

记忆操作执行

根据触发的 Skill 类型，通过AnalyticDB for PostgreSQL长记忆服务的 REST API 执行相应操作：

• 写入知识（POST /v3/memories/add/）：将结构化的开发知识写入远端记忆库。

• 语义检索（POST /v3/memories/search/）：按语义相似度搜索历史记忆。

• 记忆列表（POST /v3/memories/?page=X&page_size=Y）：分页获取用户的记忆列表。

• 更新记忆（PUT /v1/memories/{id}/）：修改已有记忆的内容。

• 删除记忆（DELETE /v1/memories/{id}/）：移除过期或无用的记忆。

结果处理与呈现

API 返回的结果经 AI 处理后以结构化方式呈现给用户——包括写入摘要、检索结果排序、健康度统计和清理建议等。

关键设计：

• IDE 自动检测：通过环境变量自动识别当前 IDE，配置文件存放在对应目录，无需手动指定。

• 项目级配置：每个项目独立一份 adbpgmem.conf，不同项目可以使用不同的 API 地址和用户标识。

• REST API 通信：所有记忆操作通过 HTTP API 完成，支持语义搜索、智能去重、分页拉取。

步骤一：执行配置命令

在 AI IDE 对话中输入：

/adbpgmem-setup

或说“配置记忆”、“设置 adbpgmem”。

步骤二：填写配置信息

AI 会依次询问三个配置项：

如果已有配置，可选择“保持不变”沿用旧值，或输入新值覆盖。

步骤三：连通性测试

配置完成后会自动进行连通性测试（最多重试 2 次）：

• HTTP 200：连通成功，配置写入。

• HTTP 401/403：Token 无效，需重新输入。

• 超时/连接失败：URL 有误或服务不可用。

步骤四：确认完成

配置成功后，配置文件会自动写入项目对应 IDE 的目录下：

# 配置文件路径示例
Qoder 项目:     .qoder/adbpgmem.conf

配置文件内容示例：

# ============================================================
# adbpgmem x AI IDE 集成配置
# 文件权限: chmod 600 (含 API Token)
# ============================================================

# ── 连接 ──
ADBPGMEM_API_URL="http://192.168.1.100:8000"
ADBPGMEM_API_TOKEN="your-api-token-here"

# ── 用户标识 (user_id，仅为用户名，非项目名) ──
# 优先级: 此值 > whoami
ADBPGMEM_USER_ID="zhangsan"

配置的更新与删除

• 重新配置：执行 /adbpgmem-setup，选择“重新配置”，可修改部分或全部参数。

• 删除配置：执行 /adbpgmem-setup，选择“删除”，会移除配置文件。

知识记录（record）

触发方式（任选其一）：

• 斜杠命令：/adbpgmem-record

• 自然语言：“记住这个”、“记录一下”、“这个坑要记住”、“这个经验很重要”、“以后别再犯这个错”

• AI 主动建议：当对话产生高价值知识时，AI 会主动建议记录。

工作流程：

1. 识别知识：从当前对话中识别高价值知识，按三要素结构化。

2. 自动查重：通过语义搜索检查是否已有高度相似的记忆（score > 0.85），有则更新，无则创建。

3. 写入记忆库：使用 jq 安全构造 JSON，避免特殊字符导致写入失败。

4. 输出摘要：展示写入结果。

知识分类：

输出示例：

已写入 2 条记忆到 adbpgmem（用户：zhangsan）
1. Kafka offset 提交使用手动模式避免重复消费
2. 订单服务超时阈值从 3s 调整为 5s 的原因

注意事项：

• 每次最多捕获 5 条记忆，超出时让用户选择最重要的。

• 如果本次对话没有值得记录的高价值知识，会直接告知用户并结束。

• 不要记录密码、API Key、Token、个人身份信息、生产环境 IP。

• 包含 <private> 标签的内容会被自动丢弃。

知识召回（recall）

触发方式：

• 斜杠命令：/adbpgmem-recall

• 自然语言：“上次怎么解决的”、“之前遇到过类似问题”、“有没有相关经验”、“这个以前踩过坑”

• AI 主动建议：当 AI 判断当前问题可能有历史先例时。

工作流程：

1. 理解意图：从用户问题中提取检索主题、关键词、时间范围和项目范围。

2. 语义搜索：通过AnalyticDB for PostgreSQL语义搜索 API 检索相关记忆（默认 top_k=5）。

3. 筛选排序：过滤 score < 0.5 的低相关结果，按相关度降序排列。

4. 结构化呈现：以类型标签 + 内容 + 相关度的格式展示结果。

跨项目检索：如果需要跨项目检索，去掉 user_id 过滤条件，扩大搜索范围（top_k=10）。

输出示例：

找到 3 条相关历史记忆：

1. [solution] Kafka offset 提交使用手动模式避免重复消费（相关度：0.92）
   详情：自动提交模式下，消费者崩溃重启后会从上次提交的 offset 之后开始...
   记录时间：2025-05-15

2. [debug] Kafka 消费者 group 重平衡导致消息丢失（相关度：0.75）
   详情：max.poll.interval.ms 设置过小，处理耗时超过该值会触发重平衡...
   记录时间：2025-04-20

3. [pattern] 消息队列消费者统一使用 @KafkaListener 注解（相关度：0.65）
   记录时间：2025-03-10

注意事项：

• 搜索查询截断到 500 字符，避免 API 超限。

• 单次最多返回 10 条结果。

• 无匹配时，建议尝试不同关键词或使用 /adbpgmem-record 记录当前经验。

记忆维护（review）

触发方式：

• 斜杠命令：/adbpgmem-review

• 自然语言：“清理记忆”、“看看记了什么”、“记忆有多少了”、“review 一下记忆”

建议频率：每月一次，或每积累 50 条新记忆后执行一次。

工作流程：

1. 拉取记忆：通过列表 API 分页获取记忆（默认最多 200 条）。

2. 统计面板：按类型和时间维度生成健康度报告。

3. 识别问题：标记过期、低质、重复、孤立四类问题记忆。

4. 呈现建议：展示问题清单和推荐操作，等待用户逐条确认。

5. 执行清理：按确认结果执行更新或删除。

6. 提权建议：识别高价值记忆（architecture/pattern 类型），建议同步到 AGENTS.md。

7. 输出总结：展示操作统计和当前记忆总数。

问题记忆识别标准：

输出示例：

=== 记忆库健康度报告 ===
项目：my-project
总记忆数：83 条（本次分析 83 条）

按类型分布：
  architecture（架构决策）：8 条
  solution（解决方案）：15 条
  pattern（编码模式）：12 条
  debug（调试经验）：9 条
  context（项目上下文）：3 条
  未分类：36 条

发现以下需要关注的记忆：

[过期]（2条）
  1. "测试环境数据库地址是 10.0.0.5" → 建议删除

[重复]（1组）
  1. "Kafka offset 手动提交"与"Kafka 消费者 offset 管理" → 建议合并

清理完成：更新 1 条，删除 2 条，合并 1 组
提权建议：2 条架构决策建议同步到 AGENTS.md
当前记忆总数：44 条
========================

注意事项：

• 列表 API 支持分页（每页 50 条），默认最多拉取 200 条。

• 更新和删除操作需要用户逐条确认，不会批量自动执行。

• 更新后的记忆总长度不超过 2000 token，超出时先汇总压缩。

场景一：Bug 排查闭环

开发者：这个订单接口响应时间从 200ms 飙到了 5s，帮我查一下
AI：（排查过程... 发现是 N+1 查询）已修复，在 OrderRepository 中添加了 JOIN FETCH
开发者：记录一下这个坑
AI：→ 触发 /adbpgmem-record，写入 [debug] 类型记忆

下次遇到类似问题：

开发者：用户列表接口又慢了，之前有没有类似的经验？
AI：→ 触发 /adbpgmem-recall
AI：根据历史记忆，上次订单接口也是 N+1 查询问题，
    通过在 Repository 中添加 JOIN FETCH 解决。建议先检查 SQL 日志。

场景二：团队协作知识共享

新成员加入项目：
开发者：有没有这个项目的开发经验和注意事项？
AI：→ 触发 /adbpgmem-recall（跨项目检索模式）
AI：找到 12 条团队历史记忆：
    1. [architecture] 选择 PostgreSQL 而非 MySQL，因为需要 JSONB 支持
    2. [pattern] 所有 REST API 统一返回 ApiResponse 包装类
    3. [debug] Redis 集群模式下 KEYS 命令会阻塞，必须用 SCAN
    ...

场景三：多 IDE 协同开发

在 Qoder 中配置（自动检测 .qoder/ 目录）：
/adbpgmem-setup  → 配置写入 .qoder/adbpgmem.conf

在 Cursor 中配置同一服务（自动检测 CURSOR_AGENT 环境变量）：
/adbpgmem-setup  → 配置写入 .cursor/adbpgmem.conf

两个 IDE 共享同一个长记忆服务和 User ID，记忆互通。
在 Qoder 中记录的知识，在 Cursor 中也能检索到。