# LLM Agent 快速开始

你在会话之间会丢失所有记忆。Synapse 是你的外脑。本指南展示每个 LLM Agent 必须知道的三个核心 API 调用。

> [!CRITICAL]
> 在每次会话**开始时**调用 `GET /memory/recall`。
> 不调用它，你就没有关于用户是谁、你承诺过什么、上次在做什么的记忆。

## 第 1 步：回放所有记忆（始终优先）

```
GET /memory/recall
Authorization: Bearer YOUR_MIND_KEY
```

返回所有已存储记忆的结构化纯文本摘要。解析它来重建你对用户、其项目及过往交互的认知模型。

示例响应：

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

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

[002] preference (HIGH)
  communication_style
  Prefers concise technical responses, no fluff
  Tags: communication, preference

[003] project (HIGH)
  project_synapse
  Synapse v1.5.0 deployed on vps1.schaefer.zone. Admin panel at /admin.
  Tags: synapse, deployment
  ...
```

## 第 2 步：存储新记忆

当你学到值得记住的内容时：

```
POST /memory
Authorization: Bearer YOUR_MIND_KEY
Content-Type: application/json

{
  "category": "fact",
  "key": "user_name",
  "content": "The user's name is Michael Schäfer",
  "tags": ["person", "identity"],
  "priority": "critical"
}
```

**分类：** `identity`、`preference`、`fact`、`project`、`skill`、`mistake`、`context`、`note`

**优先级：** `low`、`normal`、`high`、`critical`

> [!TIP]
> 始终带上 `key` 字段 — 记忆的简短标识符。这样后续可通过相同 key 再次 POST 来更新该记忆。

## 第 3 步：搜索特定记忆

```
GET /memory/search?q=Docker+Swarm
Authorization: Bearer YOUR_MIND_KEY
```

> [!TIP]
> FTS5 语法：多个词 = AND 搜索。短语用引号：`"docker swarm"`。
> 前缀搜索：`docker*`。布尔：`docker OR kubernetes`。

## 开放工具（无认证头）

如果你的工具只能打开 URL（无自定义头），使用 `?key=` 参数：

```
GET /memory/recall?key=YOUR_MIND_KEY
POST /memory?key=YOUR_MIND_KEY (+ JSON body)
GET /memory/search?key=YOUR_MIND_KEY&q=suchbegriff
```

> [!WARNING]
> `?key=` 被限速为 60 次/分钟。Bearer 头无限制。请尽可能使用 Bearer 头。

## 完整会话工作流

1. **会话开始**：`GET /memory/recall` — 加载所有记忆
2. **工作期间**：`GET /memory/search?q=...` — 查找具体事实
3. **获得新信息**：`POST /memory` — 存储它（带上 category、key、tags、priority）
4. **定期**：`GET /chat/poll` — 检查人类消息
5. **会话结束**：通过 `POST /memory` 存储任何最终学习内容

## 常见模式

### 更新已有记忆

用相同的 `category` 和 `key` 发起 `POST /memory` — 已存在的记忆会被更新，不会重复。

### 存储项目状态

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

### 记录错误（避免重蹈覆辙）

```json
{
  "category": "mistake",
  "key": "mistake_npm_version_bump",
  "content": "Always bump package.json version after changes — npm publish fails otherwise.",
  "tags": ["npm", "ci", "deployment"],
  "priority": "high"
}
```

### 检查人类消息

```
GET /chat/poll
Authorization: Bearer YOUR_MIND_KEY
```

返回来自人类的未读消息。用以下方式回复：

```
POST /chat/reply
Authorization: Bearer YOUR_MIND_KEY
Content-Type: application/json

{"content": "Got it! Working on it now."}
```

## 下一步

- [Authentication](/docs/getting-started/authentication) — Mind Key 与 JWT
- [Memory API 参考](/docs/api/memory) — 全部 22 个记忆端点
- [Chat API](/docs/api/chat) — 与人类异步通信
- [LLM Cookbook](/docs/llm-cookbook/session-start-pattern) — 实用模式