# 记忆最佳实践

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

## 分类：选择最具体的

| 分类 | 用于 | 示例 |
|----------|---------|---------|
| `identity` | 用户名、角色、联系方式 | `"user_name": "Michael Schäfer"` |
| `preference` | 喜好、厌恶、工作风格 | `"communication": "Prefers concise responses"` |
| `fact` | 可验证的事实 | `"office_location": "Berlin, Germany"` |
| `project` | 项目状态、决策 | `"project_synapse": "v1.5.0 deployed"` |
| `skill` | 用户的技能 | `"skill_python": "Advanced, 10+ years"` |
| `mistake` | 要避免的过往错误 | `"mistake_npm_version": "Always bump version"` |
| `context` | 与会话相关的上下文 | `"current_focus": "Working on docs system"` |
| `note` | 其他备注 | `"note_idea": "Try Redis for caching"` |

> [!TIP]
> 拿不准时，可验证信息用 `fact`，其他都用 `note`。
> 不要过度分类 — 清晰的 `fact` 比含糊的 `context` 更好。

## 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 个标签：

```json
{
  "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`

> [!NOTE]
> 标签不区分大小写。请使用小写以保持一致。

## 优先级：实事求是

| 优先级 | 用于 | 占比 |
|----------|---------|---------------|
| `critical` | 用户身份、法律信息、不可逆决策 | ~5% |
| `high` | 进行中的项目、重要偏好 | ~20% |
| `normal` | 大多数事实、备注、上下文 | ~65% |
| `low` | 临时、知道就好的信息 | ~10% |

> [!WARNING]
> 不要把所有记忆都标为 `critical`。如果一切都是 critical，那就什么都不是。
> 把 `critical` 留给那些一旦被遗忘就会造成实际伤害的内容。

## 何时存储、何时不存储

### 始终存储

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

### 不要存储

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

## 更新记忆

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

```python
# 初始存储
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")
```

> [!TIP]
> 使用稳定的 key，这样你可以更新而不创建重复。LLM 应该在信息变化时重新 POST 相同的 key，而不是创建新记忆。

## 记忆生命周期

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

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

### 定期清理

```python
# 查找 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")
```

## 模式：记忆继承

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

```python
# 父项目
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 不会重新质疑：

```python
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")
```

## 模式：错误规避

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

```python
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")
```

## 应避免的反模式

> [!WARNING]
> - **存储对话日志** — 聊天系统会处理
> - **存储整个文件** — 用脚本存储或外部存储
> - **存储临时状态** — 用变量
> - **存储密钥** — 用环境变量
> - **重复记忆** — 用稳定的 key
> - **过度打标签** — 每条记忆 2-5 个标签最理想
> - **一切都是 critical** — 优先级要实事求是

## 下一步

- [Memory API](/docs/api/memory)
- [持久化 LLM Agent](/docs/guides/persistent-llm-agent)
- [记忆打标签策略](/docs/llm-cookbook/memory-tagging-strategy)