# 记忆管理指南

记忆是 TokST 中的基本信息单元。记忆会被标记并组织到知识库中；配置的嵌入服务可用时，内容会生成 1536 维向量。

## 记忆类型

选择最符合您所存储信息描述的类型。

| 类型 | 用例 | 示例 |
|---|---|---|
| `fact` | 可验证的客观信息 | "API 网关 URL 是 https://api.tokst.com" |
| `decision` | 已做出的选择及其理由 | "选择 Supabase 而非 Firebase，因为其原生 Postgres 工具" |
| `preference` | 主观偏好 | "对于简单的 CRUD 端点，偏好 REST 而非 GraphQL" |
| `task` | 任务、待办事项或行动项 | "在周五前将遗留用户迁移到新的认证流程" |
| `architecture` | 系统设计或架构说明 | "认证流程使用 JWT，1 小时过期时长，自动刷新" |
| `note` | 一般信息（默认） | "与团队开会，讨论了 Q3 路线图优先级" |

```bash
tokst remember "The database runs on Supabase Postgres" --type fact
tokst remember "Use Turborepo for monorepo management" --type decision --tags architecture,infra
```

## 使用结构化 Markdown

短事实适合直接使用纯文本。决策、架构、会议纪要和任务适合使用 Markdown，使记忆在后台中易于阅读和检索。

| 类型 | 建议结构 |
|---|---|
| `fact` | 结论、来源、适用范围 |
| `decision` | 决策、背景、理由、影响 |
| `preference` | 偏好、适用情境、避免事项 |
| `task` | 目标、任务清单、完成标准 |
| `architecture` | 目标、组成、数据流、约束 |
| `note` | 摘要、内容、后续行动 |

后台编辑器提供以上模板和 Markdown 格式工具。CLI 写入长内容时，建议使用 Markdown 文件：

```bash
tokst remember --type decision --tags api,auth --stdin < decision.md
```

智能体使用相同结构记录已确认的长期信息。密钥、私钥、原始推理和临时工具输出保留在当前运行环境中。

## 种类 (Kind)

每条记忆都包含一个 `kind` 字段，描述其派生方式：

| 种类 | 描述 |
|---|---|
| `raw` | 直接记录的原始信息 |
| `summary` | 经过提炼或浓缩的信息版本 |
| `snapshot` | 上下文的时间点快照 |

种类是自动分配的，但可以覆盖。

## 来源类型

跟踪记忆的来源：

| 来源 | 描述 |
|---|---|
| `human` | 通过 CLI 或仪表盘由人工记录 |
| `agent` | 通过 MCP 由 AI 智能体创建 |
| `import` | 从外部系统导入 |
| `system` | 由 TokST 内部生成（例如，自动路由） |

```bash
tokst remember "Auto-scaling group configured for 2-10 instances" --source-type agent --source codex
```

## 标签

标签是用于筛选和发现的逗号分隔标签。与类型（互斥）不同，标签是累加的——一条记忆可以有多个标签。

```bash
tokst remember "Deploy process documented in Notion" --tags deploy,documentation,notion
```

标签支持筛选搜索：

```bash
tokst search "deploy" --tags production
tokst search "architecture" --type decision
```

## 搜索

TokST 使用**关键词优先、语义回退**的搜索流程：

1. **关键词匹配** — 对记忆内容的传统文本搜索
2. **语义向量搜索** — 1536 维空间中的嵌入相似度

关键词直接命中会立即返回并跳过嵌入请求。没有关键词结果时，TokST 会生成查询嵌入，并在认证用户及其可访问工作区范围内执行 1536 维向量搜索。

```bash
tokst search "database connection issues"       # 语义搜索
tokst search "Supabase connection string"       # 关键词匹配
tokst search "auth" --type architecture         # 筛选搜索
tokst search "api" --limit 20 --json            # 带选项的搜索
```

## 上下文快照

`context` 命令生成当前知识库中最近记忆的格式化快照。这对于为 AI 智能体提供对话上下文特别有用。

```bash
tokst context                         # 当前知识库
tokst context --atlas <id>            # 指定知识库
tokst context --limit 50              # 更多记忆
```

输出包括记忆内容、类型、标签和时间戳，采用人类和智能体均可读的格式。

## 记忆生命周期

记忆经历三个状态：

```
活跃  -->  已归档  -->  已删除
```

| 状态 | 描述 | 在搜索中可见？ | 可恢复？ |
|---|---|---|---|
| **活跃** | 正常，可搜索 | 是 | — |
| **已归档** | 软隐藏，不出现在默认结果中 | 否 | 是（`restore`） |
| **已删除** | 永久移除 | 否 | 否 |

```bash
tokst memory archive <id>     # 软隐藏
tokst memory restore <id>     # 恢复
tokst memory delete <id>      # 永久删除
```

## 可信记忆生命周期

对于事实、决策和规则等需要明确来源或审核轨迹的内容，可使用可信元数据。

| 字段 | 用途 |
|---|---|
| `evidence` | 支撑记忆的 URL 或文件路径 |
| `confidence` | `0` 到 `1` 的可信度评分 |
| `validUntil` | 可选 ISO 时间，到期后记录需要复核 |
| `reviewStatus` | `unreviewed`、`verified`、`needs_review` 或 `superseded` |

```bash
tokst memory verify mem_xxx --evidence https://example.com/policy --confidence 0.95
tokst memory verify mem_xxx --valid-until 2027-01-01T00:00:00Z
tokst memory supersede mem_old mem_new
```

验证会保留原记忆并标记为已审核。替代会将旧记忆关联到新记忆，并将旧记录标记为 `superseded`，便于持续追溯历史上下文。

## 嵌入

存储记忆或修改内容时，TokST 会请求嵌入向量。嵌入过程：

- 在服务已配置且可用时生成 **1536 维向量**
- 在写入时在服务器端运行
- 是透明的——您永远不需要直接操作向量
- 为语义回退查询提供支持

嵌入服务未配置时仍可写入记忆，关键词搜索继续可用；生成嵌入后即可使用语义回退。

## 文件附件

记忆可以通过 `--file` 标志附加文件。请参阅[文件附件指南](attachments)了解详情。

```bash
tokst remember "Sprint planning notes" --file sprint-planning.pdf
tokst memory attach <id> --file diagram.png
```

## 批量导入

从文件夹批量导入文件为记忆。文本文件（md、代码、json、csv 等）自动提取内容；二进制文件作为附件上传。

```bash
tokst import ./docs --dry-run                  # 预览
tokst import ./docs --type note --tags imported # 导入
```

请参阅 [CLI 参考](cli#批量导入) 了解所有参数。

## 最佳实践

- **一致使用类型** — 这使筛选搜索更可靠
- **多用标签** — 标签是跨领域组织的主要机制
- **归档而非删除** — 归档的记忆在需要时可以恢复
- **获取上下文快照** — 在智能体会话前运行 `tokst context` 以提供背景信息
- **追加到现有记忆** — 在添加相关信息时使用 `append` 而非创建重复内容