pma-mem

Knowledge Palace

捕获和检索项目知识。存储后端：Memos（$MEMOS_URL、$MEMOS_TOKEN）。

常驻规则

1. 执行任何操作前，确认 $MEMOS_URL 和 $MEMOS_TOKEN。如果缺少，请询问用户。
2. 每条知识记录都必须有一个类型标签。
3. 写入前，始终按 topicHash 检查是否存在重复项。
4. 一条备忘 = 一个知识点。切勿将多个主题合并到一条备忘中。
5. 相关知识点必须通过备忘关系（REFERENCE）进行关联。
6. 实施之前：先查询相关知识。检查是否存在适用于当前任务的已有决策、发现和模式。

何时查询

Agent 在以下情况下应查询知识库：

• 遇到错误或意外行为时：查询 #discovery + 关键词 — 可能有人之前遇到过
• 做出技术选择时：查询 #decision + 关键词 — 检查是否已有决策及其原因
• 实施某种模式时：查询 #pattern + 关键词 — 复用经过验证的方法
• 验证假设时：查询 #fact + 关键词 — 在此基础上构建之前先确认

知识类型

共 5 种类型，使用扁平标签，每条备忘恰好一个：

#fact · #event · #discovery · #decision · #pattern

其他标签可选且不受限制 — Agent 根据内容决定。

完整的分类规则、内容指南和质量检查：请参阅 references/classification.md。

备忘格式

## {title}

{content — preserve context and reasoning, not just the conclusion}

#fact

• 底部注释是元数据：topicHash（去重键，取标题 md5 的前 8 个字符）+ from:（知识来源，例如 session、bkd/issueId、manual）
• 标签放在内容正文中，而非元数据中

操作

写入

AUTH="Authorization: Bearer $MEMOS_TOKEN"
API="$MEMOS_URL/api/v1"

# 1. Check duplicate by topicHash
HASH=$(echo -n "Title here" | md5sum | cut -c1-8)
EXISTS=$(curl -s -H "$AUTH" \
  "$API/memos?filter=content.contains(\"$HASH\")" \
  | jq '.memos | length')

# 2. Create (if not exists)
curl -s -X POST -H "$AUTH" -H 'Content-Type: application/json' \
  "$API/memos" \
  -d '{"content":"## Title\n\nContent\n\n#fact\n\n","visibility":"PRIVATE"}' | jq

# 3. Update (if exists and changed)
curl -s -X PATCH -H "$AUTH" -H 'Content-Type: application/json' \
  "$API/memos/{uid}?updateMask=content" \
  -d '{"content":"...updated..."}' | jq

# 4. Link related memos
curl -s -X PATCH -H "$AUTH" -H 'Content-Type: application/json' \
  "$API/memos/{uid}/relations" \
  -d '{"relations":[{"relatedMemo":"memos/{otherUid}","type":"REFERENCE"}]}' | jq

查询

行动前使用查询检索知识。将内容返回到 Agent 上下文中。

# By type
curl -s -H "$AUTH" "$API/memos?filter=tag+in+[\"discovery\"]" \
  | jq '.memos[]|{uid,snippet}'

# By type + keyword
curl -s -H "$AUTH" "$API/memos?filter=tag+in+[\"decision\"]" \
  | jq '.memos[]|.content' | grep -i "keyword"

# Full-text search
curl -s -H "$AUTH" \
  "$API/memos?filter=content.contains(\"keyword\")" \
  | jq '.memos[]|{uid,snippet}'

# Get full content
curl -s -H "$AUTH" "$API/memos/{uid}" | jq '.content'

# Follow links
curl -s -H "$AUTH" "$API/memos/{uid}/relations" \
  | jq '.relations[].relatedMemo'

捕获

在对话过程中，当用户说“记住这个”/“保存这个”/“存储这个”时， 或当 Agent 发现值得保留的知识时：

1. 从当前对话中提取一个或多个知识点
2. 为每个知识点分配类型和标签，并生成 topicHash
3. 去重 → 创建/更新 → 如果有多个知识点，则进行关联

Agent 还应主动建议捕获以下内容：

• 通过调试确认的非显而易见的技术事实
• 权衡各种方案后做出的决策
• 实施过程中发现的注意事项或陷阱
• 效果良好的可复用模式或工作流

整理

按需进行：用户要求清理，或 Agent 在查询时发现备忘内容重叠。

1. 加载一个标签组：curl -s -H "$AUTH" "$API/memos?filter=tag+in+[\"auth\"]&pageSize=100" | jq
2. 检查是否存在近似重复、已被取代的事实或片段
3. 合并为一条备忘，并归档原始备忘 — 详情请参阅 references/knowledge-sync.md

参考资料包

• references/classification.md 类型定义、内容指南、标签规则、质量检查和整理规则。
• references/storage-api.md Memos REST API 参考（CRUD、筛选器、关系、分页、附件）。
• references/knowledge-sync.md 自动同步工作流：扫描、提取、去重、增量更新和自动化指南。

快速路由

• 对知识进行分类或格式化：加载 references/classification.md。
• API 详细信息（updateMask、筛选器、错误代码）：加载 references/storage-api.md。
• 从任务系统自动同步：加载 references/knowledge-sync.md。
• 简单捕获或查询：直接使用上述操作。