记忆管理指南
记忆是 TokST 中的基本信息单元。记忆会被标记并组织到知识库中；配置的嵌入服务可用时，内容会生成 1536 维向量。
记忆类型
选择最符合您所存储信息描述的类型。
| 类型 | 用例 | 示例 |
|---|---|---|
fact | 可验证的客观信息 | "API 网关 URL 是 https://api.tokst.com" |
decision | 已做出的选择及其理由 | "选择 Supabase 而非 Firebase，因为其原生 Postgres 工具" |
preference | 主观偏好 | "对于简单的 CRUD 端点，偏好 REST 而非 GraphQL" |
task | 任务、待办事项或行动项 | "在周五前将遗留用户迁移到新的认证流程" |
architecture | 系统设计或架构说明 | "认证流程使用 JWT，1 小时过期时长，自动刷新" |
note | 一般信息（默认） | "与团队开会，讨论了 Q3 路线图优先级" |
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 文件：
tokst remember --type decision --tags api,auth --stdin < decision.md
智能体使用相同结构记录已确认的长期信息。密钥、私钥、原始推理和临时工具输出保留在当前运行环境中。
种类 (Kind)
每条记忆都包含一个 kind 字段，描述其派生方式：
| 种类 | 描述 |
|---|---|
raw | 直接记录的原始信息 |
summary | 经过提炼或浓缩的信息版本 |
snapshot | 上下文的时间点快照 |
种类是自动分配的，但可以覆盖。
来源类型
跟踪记忆的来源：
| 来源 | 描述 |
|---|---|
human | 通过 CLI 或仪表盘由人工记录 |
agent | 通过 MCP 由 AI 智能体创建 |
import | 从外部系统导入 |
system | 由 TokST 内部生成（例如，自动路由） |
tokst remember "Auto-scaling group configured for 2-10 instances" --source-type agent --source codex
标签
标签是用于筛选和发现的逗号分隔标签。与类型（互斥）不同，标签是累加的——一条记忆可以有多个标签。
tokst remember "Deploy process documented in Notion" --tags deploy,documentation,notion
标签支持筛选搜索：
tokst search "deploy" --tags production
tokst search "architecture" --type decision
搜索
TokST 使用关键词优先、语义回退的搜索流程：
- 关键词匹配 — 对记忆内容的传统文本搜索
- 语义向量搜索 — 1536 维空间中的嵌入相似度
关键词直接命中会立即返回并跳过嵌入请求。没有关键词结果时，TokST 会生成查询嵌入，并在认证用户及其可访问工作区范围内执行 1536 维向量搜索。
tokst search "database connection issues" # 语义搜索
tokst search "Supabase connection string" # 关键词匹配
tokst search "auth" --type architecture # 筛选搜索
tokst search "api" --limit 20 --json # 带选项的搜索
上下文快照
context 命令生成当前知识库中最近记忆的格式化快照。这对于为 AI 智能体提供对话上下文特别有用。
tokst context # 当前知识库
tokst context --atlas <id> # 指定知识库
tokst context --limit 50 # 更多记忆
输出包括记忆内容、类型、标签和时间戳，采用人类和智能体均可读的格式。
记忆生命周期
记忆经历三个状态：
活跃 --> 已归档 --> 已删除
| 状态 | 描述 | 在搜索中可见？ | 可恢复？ |
|---|---|---|---|
| 活跃 | 正常，可搜索 | 是 | — |
| 已归档 | 软隐藏，不出现在默认结果中 | 否 | 是（restore） |
| 已删除 | 永久移除 | 否 | 否 |
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 |
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 标志附加文件。请参阅文件附件指南了解详情。
tokst remember "Sprint planning notes" --file sprint-planning.pdf
tokst memory attach <id> --file diagram.png
批量导入
从文件夹批量导入文件为记忆。文本文件（md、代码、json、csv 等）自动提取内容；二进制文件作为附件上传。
tokst import ./docs --dry-run # 预览
tokst import ./docs --type note --tags imported # 导入
请参阅 CLI 参考 了解所有参数。
最佳实践
- 一致使用类型 — 这使筛选搜索更可靠
- 多用标签 — 标签是跨领域组织的主要机制
- 归档而非删除 — 归档的记忆在需要时可以恢复
- 获取上下文快照 — 在智能体会话前运行
tokst context以提供背景信息 - 追加到现有记忆 — 在添加相关信息时使用
append而非创建重复内容