# 记忆模型

Synapse 的记忆模型专为 LLM Agent 设计 — 既结构化以保证可靠回放，又足够灵活以适应任何领域。

## 记忆结构

```json
{
  "id": "mem_abc123",
  "category": "project",
  "key": "project_synapse_status",
  "content": "Synapse v1.5.0 deployed on vps1. CI green.",
  "tags": ["synapse", "deployment", "v1.5.0"],
  "priority": "high",
  "source": "agent",
  "verified": false,
  "confidence": 0.85,
  "expires_at": null,
  "mind_id": "m_xyz789",
  "created_at": "2026-06-27T...",
  "updated_at": "2026-06-27T..."
}
```

## 字段

| 字段 | 类型 | 必填 | 说明 |
|-------|------|----------|-------------|
| `id` | string | 自动 | 唯一 ID（mem_xxx） |
| `category` | enum | ✅ | 8 种分类之一 |
| `key` | string | ✅ | 稳定标识符（用于更新） |
| `content` | string | ✅ | 记忆内容（任意文本） |
| `tags` | string[] | – | 用于搜索和过滤 |
| `priority` | enum | – | low、normal、high、critical（默认：normal） |
| `source` | enum | 自动 | user、agent（存储者） |
| `verified` | bool | 自动 | 是否经过人类验证 |
| `confidence` | float | – | 0.0 到 1.0（user 默认 1.0，agent 默认 0.7） |
| `expires_at` | timestamp | – | 何时遗忘此记忆 |
| `mind_id` | string | 自动 | 所属 Mind |
| `created_at` | timestamp | 自动 | 首次存储时间 |
| `updated_at` | timestamp | 自动 | 最后修改时间 |

## 分类

八种分类覆盖了常见的 LLM Agent 用例：

| 分类 | 用途 | 内容示例 |
|----------|---------|-----------------|
| `identity` | 用户是谁 | "User is Michael Schäfer, software engineer in Berlin" |
| `preference` | 用户偏好 | "Prefers concise technical responses" |
| `fact` | 可验证的事实 | "Office is in Berlin, timezone Europe/Berlin" |
| `project` | 项目状态 | "Synapse v1.5.0 deployed, working on v1.6.0 docs" |
| `skill` | 用户的技能 | "Advanced Python, 10+ years" |
| `mistake` | 过去犯的错 | "Forgot to bump npm version — CI failed" |
| `context` | 会话上下文 | "Currently reviewing PR #42" |
| `note` | 其他备注 | "Try Redis for caching next sprint" |

## Key：稳定标识符

`key` 字段至关重要 — 它是更新记忆而不产生重复的方式。

```python
# 首次存储
store("project", "project_synapse_status", "v1.4.0 deployed", priority="high")

# 用相同的 key 更新（覆盖，不重复）
store("project", "project_synapse_status", "v1.5.0 deployed", priority="high")
```

**Key 规则：**

- 在 (category, mind) 内必须唯一
- 使用 `snake_case`
- 以分类为前缀提高可读性：`preference_communication`、`mistake_npm_version`
- 创建后不要修改 key

## Tags：用于搜索

标签可加速过滤与搜索：

```bash
# 查找所有带 "docker" 标签的记忆
GET /memory/by-tag?tag=docker

# 在带标签的子集中进行 FTS5 搜索
GET /memory/search?q=swarm&tag=docker
```

**标签最佳实践：**

- 每条记忆 2-5 个标签（不要过度打标签）
- 使用小写以保持一致
- 使用项目名、主题、技术名
- 标签不区分大小写

## 优先级

| 优先级 | 何时使用 | 回放行为 |
|----------|-------------|-----------------|
| `critical` | 身份、法律、不可逆信息 | 始终位于回放顶部 |
| `high` | 进行中的项目、关键偏好 | 回放中突出显示 |
| `normal` | 大多数记忆（默认） | 标准回放顺序 |
| `low` | 临时、知道就好的信息 | 可能被摘要 |

`/memory/recall` 按优先级排序（critical 在前），其次按时间。

## 来源：User 与 Agent

记忆用 `source` 标记：

- `user` — 由人类存储（通过 JWT 或人类 UI）
- `agent` — 由 LLM Agent 存储（通过 Mind Key）

这会影响：

- **验证**：`user` 记忆自动验证，`agent` 记忆不自动验证
- **置信度**：`user` 默认 1.0，`agent` 默认 0.7
- **回放**：`/memory/recall` 会标记未验证记忆为 "(unverified)"

> [!NOTE]
> 对 `agent` 来源的记忆应保持适当的怀疑。它们可能是推断或假设而来，而非用户直接陈述。

## 验证

`verified` 标志表示人类已确认该记忆：

- `user` 记忆：自动验证（`true`）
- `agent` 记忆：默认未验证（`false`）

通过以下方式验证记忆：

```bash
curl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \
  -H "Authorization: Bearer YOUR_JWT"
```

> [!NOTE]
> 验证需要 JWT（人类认证），而非 Mind Key（Agent 认证）。这确保只有人类才能将记忆标记为已验证。

## 置信度

`confidence` 字段（0.0 到 1.0）表示记忆的可靠程度：

- 1.0 — 用户直接陈述
- 0.7 — 由 Agent 推断
- 0.5 — 不确定，需要验证
- 0.0 — 明确存疑

存储时设置置信度：

```json
{
  "category": "preference",
  "key": "prefers_dark_mode",
  "content": "User seems to prefer dark mode (based on their IDE screenshots)",
  "confidence": 0.5,
  "source": "agent"
}
```

## 过期

为时效性记忆设置 `expires_at`：

```json
{
  "category": "context",
  "key": "current_meeting_topic",
  "content": "Discussing Q3 roadmap",
  "expires_at": "2026-06-28T00:00:00Z"
}
```

已过期的记忆不会出现在 `/memory/recall` 中（但仍在数据库中）。使用 `/memory/expiring?within=7d` 查看即将过期的记忆。

## 记忆生命周期

```
                  ┌─────────────────┐
                  │     创建        │
                  │  POST /memory   │
                  └────────┬────────┘
                           │
                           ▼
                  ┌─────────────────┐
                  │     活跃        │ ◀──── PUT /memory/:id (更新)
                  │  (在回放中)     │
                  └────────┬────────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
              ▼            ▼            ▼
        ┌──────────┐ ┌──────────┐ ┌──────────┐
        │ 已过期   │ │ 已验证   │ │ 已删除   │
        │ (在 DB)  │ │ (标志)   │ │ (已消失) │
        └──────────┘ └──────────┘ └──────────┘
```

## 回放行为

`GET /memory/recall` 返回为 LLM 上下文优化的纯文本摘要：

```
Mind: Michael's Mind
Memories: 12 total (10 verified, 2 unverified)

[001] identity (CRITICAL) [verified]
  user_name
  Michael Schäfer
  Tags: person, identity

[002] preference (HIGH) [verified]
  communication_style
  Prefers concise technical responses
  Tags: communication

[003] project (HIGH) [unverified]
  synapse_status
  v1.5.0 deployed, working on v1.6.0 docs
  Tags: synapse, deployment

...
```

- 按优先级排序（critical → low），其次按时间
- 未验证记忆用 `[unverified]` 标记
- 包含标签以提供上下文
- 纯文本（无需解析 JSON）

## 下一步

- [Memory API](/docs/api/memory)
- [记忆最佳实践](/docs/guides/memory-best-practices)
- [FTS5 搜索](/docs/concepts/fts5-search)