记忆最佳实践

记忆的结构决定了它的实用价值。本指南涵盖记忆的分类、打标签与优先级模式，让 LLM 能在正确时间回放出正确信息。

分类：选择最具体的

Key：有意义的标识符

key 字段是记忆的标识符。使用有意义且稳定的 key：

好 key：

• user_name
• project_synapse_status
• preference_communication_style
• mistake_npm_version_bump

坏 key：

• mem_001（无意义）
• temp（不具描述性）
• 2026-06-27-note（日期对回放无帮助）

Key 命名规范

• snake_case（小写加下划线）
• 以分类为前缀：preference_*、project_*、mistake_*
• 使用描述性名词，而非动词
• 长度控制在 50 字符以内

Tags：用于搜索与过滤

标签可加速过滤与搜索。每条记忆加 2-5 个标签：

{
  "category": "project",
  "key": "project_synapse_status",
  "content": "Synapse v1.5.0 deployed. Next: v1.6.0 with docs system.",
  "tags": ["synapse", "deployment", "status", "v1.5.0"]
}

标签模式

• 项目名：synapse、synapse-mcp、synapse-chat
• 主题：deployment、ci、database、auth
• 状态：active、completed、blocked
• 优先级指示：urgent、long-term

优先级：实事求是

何时存储、何时不存储

始终存储

• 用户身份（姓名、邮箱、角色）
• 长期偏好
• 项目决策与理由
• 过往错误与教训
• 对用户做出的承诺

不要存储

• 临时状态（改用变量）
• 逐字对话历史（聊天系统会处理）
• 敏感数据（密码、API key）
• 易推导的事实（当前日期、文件内容）
• 短暂上下文（用 context 分类 + low 优先级）

更新记忆

用相同的 category + key 发起 POST /memory 会更新已有记忆：

# 初始存储
store("project", "project_synapse_status", "v1.4.0 deployed", priority="high")

# 后续：用相同 key 更新
store("project", "project_synapse_status", "v1.5.0 deployed. CI green.", priority="high")

记忆生命周期

创建 → 活跃 → 陈旧 → 归档 → 删除

• 创建：POST /memory，带上完整上下文
• 活跃：频繁回放，按需更新
• 陈旧：仍相关但不再活跃使用（降低优先级？）
• 归档：设为 low 优先级，保留供历史参考
• 删除：不再相关时 DELETE /memory/:id

定期清理

# 查找 90 天未更新的记忆
old_memories = requests.get(
    f"{URL}/memory/search?q=*",
    headers={"Authorization": f"Bearer {KEY}"}
)

for mem in old_memories["results"]:
    if is_stale(mem, days=90):
        # 删除或降低优先级
        if is_obsolete(mem):
            delete_memory(mem["id"])
        else:
            update_memory(mem["id"], priority="low")

模式：记忆继承

对于层级上下文（项目 → 子项目 → 任务）：

# 父项目
store("project", "project_synapse", "Main Synapse project", 
      tags=["synapse", "parent"], priority="high")

# 子项目（标签关联父项目）
store("project", "project_synapse_docs", "Docs system for Synapse",
      tags=["synapse", "docs", "synapse-parent"], priority="high")

# 具体任务（标签关联子项目）
store("project", "task_docs_loader", "Implement docs-loader.ts",
      tags=["synapse", "docs", "task"], priority="normal")

LLM 之后可搜索 q=synapse+docs 找到所有相关记忆。

模式：决策日志

把决策与理由一起存储，这样 LLM 不会重新质疑：

store("fact", "decision_postgres_over_sqlite",
      "Chose PostgreSQL over SQLite for production. Reason: concurrent writes, "
      "FTS5 native support, better backup story. Date: 2026-06-15. Decided by: Michael.",
      tags=["decision", "database", "postgres", "sqlite"],
      priority="high")

模式：错误规避

把错误与具体的规避指令一起存储：

store("mistake", "mistake_forget_version_bump",
      "Forgot to bump package.json version after changes. npm publish failed. "
      "FIX: Always run `npm version patch` before pushing. "
      "CI fails with 'version already exists' if you forget.",
      tags=["npm", "ci", "publish", "version"],
      priority="high")

应避免的反模式

下一步

• Memory API
• 持久化 LLM Agent
• 记忆打标签策略