# Memory API

Memory API 是 Synapse 的核心。它提供 22 个端点用于存储、检索、搜索和管理结构化记忆。所有端点都需要 Mind Key 进行认证。

> [!CRITICAL]
> **务必在每次会话开始时调用 `GET /memory/recall`。** 这是从之前的会话中重建上下文的唯一方式。

## 分类

记忆被组织为 8 个分类：

| 分类 | 用途 |
|----------|----------|
| `identity` | 用户名、角色、联系方式、关于自身的偏好 |
| `preference` | 喜好、厌恶、工作风格、沟通偏好 |
| `fact` | 可验证的事实（项目细节、日期、URL） |
| `project` | 项目状态、里程碑、架构 |
| `skill` | 用户擅长的事情 |
| `mistake` | 过去犯的错 — 避免重蹈覆辙 |
| `context` | 与会话相关的上下文 |
| `note` | 其他备注 |

## 优先级

- `low` — 知道就好
- `normal` — 默认
- `high` — 重要
- `critical` — 绝不能忘（用户身份、法律信息等）

## 核心端点

### GET /memory/recall

以 LLM 优化的纯文本形式返回所有记忆。请务必在每次会话开始时调用。

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/recall
```

响应（text/plain）：

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

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

...
```

### POST /memory

存储新记忆或更新已有记忆（相同 category + key 视为更新）。

```bash
curl -X POST https://synapse.schaefer.zone/memory \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "fact",
    "key": "user_name",
    "content": "The user's name is Michael Schäfer",
    "tags": ["person", "identity"],
    "priority": "critical"
  }'
```

响应：`{ "id": "mem_001", "status": "stored" }`

### GET /memory

列出记忆，可加可选过滤条件。

```bash
# 全部记忆（JSON）
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?limit=50&offset=0"

# 按分类过滤
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?category=project"

# 按标签过滤
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?tag=docker"
```

### PUT /memory/:id

按 ID 更新某条具体记忆。

```bash
curl -X PUT https://synapse.schaefer.zone/memory/mem_001 \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Updated content", "priority": "high"}'
```

### DELETE /memory/:id

删除单条记忆。

```bash
curl -X DELETE -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/mem_001
```

## 搜索端点

### GET /memory/search

使用 FTS5 进行全文搜索。

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/search?q=docker+swarm"
```

FTS5 语法：

- 多个词 = AND：`docker swarm`
- 短语：`"docker swarm"`
- 前缀：`docker*`
- 布尔：`docker OR kubernetes`
- 排除：`docker -swarm`

### GET /memory/semantic-search

使用向量嵌入进行概念搜索（比 FTS5 慢，但能理解语义）。

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/semantic-search?q=container+orchestration"
```

返回与查询语义相似的记忆，即使没有关键词匹配。适用于“查找关于 X 的记忆”，即使 X 被用不同的方式描述。

### GET /memory/by-tag

按标签列出记忆。

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/by-tag?tag=docker"
```

### GET /memory/related/:id

查找与某条记忆相关的记忆（基于共享标签）。

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/related/mem_001
```

## 同步与 Diff

### GET /memory/diff

增量同步 — 返回自指定时间戳以来发生变化的记忆。

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/diff?since=1700000000"
```

响应：`{ "added": [...], "updated": [...], "deleted": [...] }`

### POST /memory/sync

应用来自另一个实例的 diff（用于自托管同步）。

```bash
curl -X POST https://synapse.schaefer.zone/memory/sync \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"added": [...], "updated": [...], "deleted": [...]}'
```

## 批量操作

### POST /memory/bulk-delete

按 ID 批量删除记忆。

```bash
curl -X POST https://synapse.schaefer.zone/memory/bulk-delete \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["mem_001", "mem_002", "mem_003"]}'
```

### POST /memory/embed-batch

为尚未生成向量嵌入的记忆批量生成嵌入（用于语义搜索）。

```bash
curl -X POST https://synapse.schaefer.zone/memory/embed-batch \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 100}'
```

### GET /memory/embed-batch-status

检查嵌入生成进度。

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/embed-batch-status
```

## 验证

记忆有 `verified` 标志。Agent 存储的记忆默认未验证（`source=agent`）；人类存储的记忆默认已验证（`source=user`）。

### POST /memory/verify

将记忆标记为已验证（需要 JWT，而非 Mind Key）。

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

### POST /memory/unverify

将记忆标记为未验证（需要 JWT）。

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

### GET /memory/unverified

列出等待人类验证的记忆。

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/unverified?limit=100"
```

## 统计与审计

### GET /memory/stats

当前 Mind 的聚合统计。

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/stats
```

返回：`{ "total": 12, "verified": 10, "unverified": 2, "by_category": {...}, "by_priority": {...} }`

### GET /memory/audit

所有状态变更操作的审计日志。

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/audit?limit=100&action=store"
```

### GET /memory/contradictions

检测已存储记忆中潜在的矛盾。

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/contradictions
```

### GET /memory/expiring

列出即将到期的记忆。

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/expiring?within=7d"
```

## 健康检查与导出

### GET /memory/health

记忆系统的快速健康检查。

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/health
```

### GET /memory/mind-export

全部记忆的完整 JSON 导出（用于备份）。

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/mind-export > backup.json
```

### POST /memory/compact

压缩相似记忆（自动摘要）。

```bash
curl -X POST https://synapse.schaefer.zone/memory/compact \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": true}'
```

## 下一步

- [LLM 快速开始](/docs/getting-started/quick-start-llm)
- [记忆最佳实践](/docs/guides/memory-best-practices)
- [FTS5 搜索](/docs/concepts/fts5-search)
- [语义搜索](/docs/concepts/semantic-search)