记忆与会话管理

Kesoku 将所有的聊天记录、绑定设定和 Agent 的记忆内容都存储在本地 SQLite 数据库中（通常为 kesoku.db）。本指南将介绍如何通过命令行管理活动的聊天会话，以及如何手动维护 Agent 的长期结构化记忆。

💬 通过命令行管理聊天会话 (Sessions)

每个对话分支都被隔离在一个唯一的会话（由 session_id 标识）中。在守护进程模式下，这些 ID 会与 Discord 的线程 ID、Google Chat 的 Space ID 或微信的聊天下发上下文进行自动映射。

您可以使用 kesoku chat 命令组来管理这些会话：

1. 列出所有活跃会话

查询数据库中记录的所有会话，并展示它们的创建时间、绑定角色以及已同步的消息条数：

kesoku chat -c config.toml -l

2. 打印会话聊天历史

在终端中以美观、带色彩的 Rich 格式打印出指定会话的完整历史对话轨迹：

kesoku chat -c config.toml --show-history <session_id>

3. 恢复会话进行聊天

在已有的特定会话中继续对话：

kesoku chat -c config.toml -r <session_id> "我们刚才提到的数字是几？"

或者，无需复制 ID，快速恢复最近一次活跃的会话：

kesoku chat -c config.toml -z "继续之前的任务。"

🧠 管理 Agent 的长期记忆 (`memory`)

Kesoku 内置了一个长期记忆模块，允许 Agent 跨会话沉淀和读取结构化知识（例如用户偏好、里程碑记录、业务配置）。这些记忆按分类 (Category) 和人设角色 (Role) 进行命名空间隔离。

管理员可以使用 kesoku memory 命令组来维护这些记忆：

1. 列出记忆条目

列出指定分类下的所有记忆（可选择过滤特定角色）：

# 列出默认角色 (default) 在 'user_preference' 分类下的所有记忆
kesoku memory list --category user_preference --role default

2. 查看具体记忆内容

查看单个记忆 Key 的详细内容与描述：

kesoku memory view --category user_preference --key user_timezone --role default

3. 添加或更新记忆

手动录入或修改一条记忆记录：

kesoku memory update --category user_preference --key user_timezone --title "用户时区" --content "Asia/Tokyo" --role default

4. 删除记忆

删除指定的记忆条目：

kesoku memory delete --category user_preference --key user_timezone --role default

5. 备份与迁移 (导出 / 导入)

如果您需要备份所有角色的记忆，或者迁移到另一个工作环境的 SQLite 数据库：

导出为 JSON 文件：

kesoku memory export -o memories_backup.json

从 JSON 文件导入：

kesoku memory import -i memories_backup.json

6. 语义搜索与向量索引重建 (`rebuild-index`)

Kesoku 支持通过本地轻量级 Embedding 模型进行多语言语义搜索。

自动索引：
- 在日常对话中，所有主动保存的记忆（Memory）以及收到的用户提问、助理回复（TEXT 类型的消息）会在写入 SQLite 时自动在后台进行向量化编码（生成 Embedding 存入 embedding 字段）。
- 为了保持清洁，Agent 的思考链路（Thoughts）和 Tool 执行结果（Tool Calls/Results）不会被向量化索引。

手动重建/全量索引：

如果你导入了旧数据，或者清空了向量字段，你可以运行 rebuild-index 来对数据库中所有未索引的文本进行增量/全量向量重构：

# 增量计算数据库中所有没有 Embedding 字段的记录
kesoku memory rebuild-index -c config.toml

# 强制清除所有已有向量，并重新为整张表计算 Embedding 索引
kesoku memory rebuild-index -c config.toml --force