## 核心功能 - 双记忆系统合并：picoclaw MEMORY.md + hxclaw 会话摘要 - 独立上下文系统：不依赖 picoclaw session - 向量检索：硅基流动 BGE-M3 API - 三重检测：关键词/向量相似度/命令 ## 数据库 - libSQL (TursoDB) 存储 - sessions + chats 表设计 - 向量存储使用 binary 编码 ## 查询场景 - RecallHistory: 查询所有会话摘要 - RecallTopic: 按话题向量检索 - RecallSession: 指定会话详情 - RecallWithinSession: 会话内检索 ## 导出 - MongoDB 风格：~/.config/hxclaw/export-data.json - chats 嵌套在 sessions 下 - 增量导出，同 session 累加 ## UI 优化 - 合并状态显示（耗时 · 状态 · 消息数） - 颜色设计：金色图标 + 暗绿色/暗红色状态 ## 配置项 - memory.recall: keywords, auto_recall, similarity_threshold - memory.vector: max_search_results - memory.auto_export
This commit is contained in:
260
docs/memory-plan.md
Normal file
260
docs/memory-plan.md
Normal file
@@ -0,0 +1,260 @@
|
||||
# hxclaw 聊天记忆体实现计划
|
||||
|
||||
## 概述
|
||||
|
||||
hxclaw 聊天记忆体是一个基于 libSQL (TursoDB) 的对话上下文管理系统，用于替代 picoclaw 原有的 memory.md 文件，实现更灵活、可控的会话历史管理。
|
||||
|
||||
**注意**：本计划文档已实现完成，详细功能请参考 `docs/discussion.md`。
|
||||
|
||||
## 技术选型
|
||||
|
||||
| 组件 | 选型 | 说明 |
|
||||
|------|------|------|
|
||||
| 数据库 | libSQL (嵌入式) | 本地文件数据库 `~/.config/hxclaw/hxclaw.db` |
|
||||
| 向量模型 | BAAI/bge-m3 | 1024 维，硅基流动 API |
|
||||
| UUID | github.com/google/uuid | 生成唯一会话 ID |
|
||||
| 第三方库 | go_modules/ | 本地化方案解决网络问题 |
|
||||
|
||||
## 数据库设计
|
||||
|
||||
### sessions 表
|
||||
```sql
|
||||
CREATE TABLE IF NOT EXISTS sessions (
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
uuid TEXT UNIQUE NOT NULL,
|
||||
summary TEXT,
|
||||
summary_embedding BLOB,
|
||||
chat_ids TEXT,
|
||||
created_at INTEGER NOT NULL,
|
||||
updated_at INTEGER NOT NULL
|
||||
);
|
||||
```
|
||||
|
||||
### chats 表
|
||||
```sql
|
||||
CREATE TABLE IF NOT EXISTS chats (
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
session_id INTEGER NOT NULL,
|
||||
user_input TEXT NOT NULL,
|
||||
ai_replies TEXT,
|
||||
summary TEXT,
|
||||
summary_embedding BLOB,
|
||||
created_at INTEGER NOT NULL,
|
||||
updated_at INTEGER NOT NULL,
|
||||
FOREIGN KEY(session_id) REFERENCES sessions(id)
|
||||
);
|
||||
```
|
||||
|
||||
## 核心流程
|
||||
|
||||
1. **Session 管理**：自动创建（首次输入）+ 手动创建（`/new`）
|
||||
2. **消息保存**：在 AI 返回后调用 `SaveChat()` 保存到数据库
|
||||
3. **查询命令**：`/memory`, `/sessions`, `/new`
|
||||
|
||||
## 配置
|
||||
|
||||
- **启用**：默认启用
|
||||
- **数据库路径**：`~/.config/hxclaw/hxclaw.db`
|
||||
- **用户配置**：`~/.config/hxclaw/config.yml`
|
||||
|
||||
## 实现状态
|
||||
|
||||
| 功能 | 状态 |
|
||||
|------|------|
|
||||
| 数据库 CRUD | ✅ 完成 |
|
||||
| 聊天记录保存 | ✅ 完成 |
|
||||
| 命令支持 | ✅ 完成 |
|
||||
| JSON 导出 | ✅ 完成 |
|
||||
| 向量服务 | ⚠️ 框架完成，待完善 |
|
||||
| 向量查询 | ⏳ 待实现 |
|
||||
|
||||
hxclaw 聊天记忆体是一个基于 TursoDB (libSQL) 的对话上下文管理系统，用于替代 picoclaw 原有的 memory.md 文件，实现更灵活、可控的会话历史管理。
|
||||
|
||||
核心目标：
|
||||
1. 保留 picoclaw 的 memory.md 作为 AI 长期记忆
|
||||
2. 新增对话记忆体作为会话维度的短期记忆
|
||||
3. 支持向量检索和多场景查询
|
||||
|
||||
## 技术选型
|
||||
|
||||
| 组件 | 选型 | 说明 |
|
||||
|------|------|------|
|
||||
| 数据库 | libSQL (嵌入式) | 本地文件数据库，支持 JSON 导出 |
|
||||
| 向量模型 | BAAI/bge-m3 | 1024 维，硅基流动 API |
|
||||
| UUID | github.com/google/uuid | 生成唯一会话 ID |
|
||||
| libSQL 驱动 | github.com/tursodatabase/go-libsql | CGO 需启用 |
|
||||
|
||||
## 数据库设计
|
||||
|
||||
### 表结构
|
||||
|
||||
```sql
|
||||
-- sessions 表（会话维度）
|
||||
CREATE TABLE IF NOT EXISTS sessions (
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
uuid TEXT UNIQUE NOT NULL, -- 外键引用用 UUID
|
||||
summary TEXT, -- 会话压缩后的摘要
|
||||
summary_embedding BLOB, -- 1024维向量（二进制）
|
||||
chat_ids TEXT, -- JSON数组 ["id1","id2",...]
|
||||
created_at INTEGER NOT NULL, -- Unix时间戳
|
||||
updated_at INTEGER NOT NULL
|
||||
);
|
||||
|
||||
-- chats 表（消息维度）
|
||||
CREATE TABLE IF NOT EXISTS chats (
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
session_id INTEGER NOT NULL, -- 外键到 sessions.id
|
||||
user_input TEXT NOT NULL, -- 用户输入
|
||||
ai_replies TEXT, -- JSON数组 [{"role":"assistant","content":"..."},...]
|
||||
summary TEXT, -- 单条消息摘要
|
||||
summary_embedding BLOB, -- 1024维向量
|
||||
created_at INTEGER NOT NULL,
|
||||
updated_at INTEGER NOT NULL,
|
||||
FOREIGN KEY(session_id) REFERENCES sessions(id)
|
||||
);
|
||||
|
||||
-- 索引
|
||||
CREATE INDEX IF NOT EXISTS idx_chats_session_id ON chats(session_id);
|
||||
CREATE INDEX IF NOT EXISTS idx_sessions_uuid ON sessions(uuid);
|
||||
```
|
||||
|
||||
### 数据模型
|
||||
|
||||
```go
|
||||
// Session 会话记录
|
||||
type Session struct {
|
||||
ID int64 `json:"id"`
|
||||
UUID string `json:"uuid"`
|
||||
Summary string `json:"summary"`
|
||||
SummaryEmbedding []byte `json:"-"`
|
||||
ChatIDs []int64 `json:"chat_ids"`
|
||||
CreatedAt int64 `json:"created_at"`
|
||||
UpdatedAt int64 `json:"updated_at"`
|
||||
}
|
||||
|
||||
// Chat 聊天记录
|
||||
type Chat struct {
|
||||
ID int64 `json:"id"`
|
||||
SessionID int64 `json:"session_id"`
|
||||
UserInput string `json:"user_input"`
|
||||
AIReplies []string `json:"ai_replies"`
|
||||
Summary string `json:"summary"`
|
||||
SummaryEmbedding []byte `json:"-"`
|
||||
CreatedAt int64 `json:"created_at"`
|
||||
UpdatedAt int64 `json:"updated_at"`
|
||||
}
|
||||
```
|
||||
|
||||
## 核心流程
|
||||
|
||||
### 1. Session 管理
|
||||
|
||||
#### 自动开始（模式 A）
|
||||
- 用户首次输入内容时，检查是否存在活跃 Session
|
||||
- 若无，则自动创建新 Session
|
||||
|
||||
#### 手动开始（模式 B）
|
||||
- 用户输入 `/new` 命令，强制创建新 Session
|
||||
|
||||
### 2. 消息处理流程
|
||||
|
||||
```
|
||||
用户输入
|
||||
↓
|
||||
[可选] 创建新 Session（首次输入时）
|
||||
↓
|
||||
chats 表插入记录 (session_id, user_input, created_at)
|
||||
↓
|
||||
AI 处理
|
||||
↓
|
||||
AI 返回后：
|
||||
1. 生成摘要 + 向量
|
||||
2. chats 表更新 (ai_replies, summary, summary_embedding)
|
||||
3. sessions 表更新 (chat_ids 追加, summary 压缩, summary_embedding 更新)
|
||||
↓
|
||||
将 Session 摘要作为上下文注入 AI
|
||||
```
|
||||
|
||||
### 3. 上下文注入
|
||||
|
||||
```
|
||||
=== 当前会话摘要 ===
|
||||
[最新摘要内容]
|
||||
===
|
||||
```
|
||||
|
||||
### 4. 查询场景（4种）
|
||||
|
||||
| 场景 | 用户意图 | 查询方式 |
|
||||
|------|----------|----------|
|
||||
| 1 | "之前聊过什么" | 查询最新 Session 的 summary |
|
||||
| 2 | "某某某相关内容" | 向量搜索 top 5 |
|
||||
| 3 | "某次谈论时的详情" | 定位 Session ID，返回 summary |
|
||||
| 4 | 同 Session 内其他相关内容 | session_id 过滤 + 向量搜索 |
|
||||
|
||||
## 模块设计
|
||||
|
||||
### 目录结构
|
||||
|
||||
```
|
||||
cmd/hxclaw/internal/memory/
|
||||
├── db.go # 数据库初始化和 CRUD 操作
|
||||
├── model.go # 数据模型定义
|
||||
├── vector.go # 向量服务（硅基流动 API）
|
||||
├── skill.go # 内置 Skill（查询逻辑）
|
||||
└── export.go # 导出功能
|
||||
```
|
||||
|
||||
## 配置项
|
||||
|
||||
在 `project.config.yml` 中新增：
|
||||
|
||||
```yaml
|
||||
# 聊天记忆体配置
|
||||
memory:
|
||||
enabled: true # 启用开关
|
||||
db_path: "./hxclaw.db" # 数据库路径
|
||||
auto_session: true # 自动创建 Session
|
||||
export_on_exit: true # 退出时导出
|
||||
|
||||
# 向量服务配置
|
||||
vector:
|
||||
api_key: "sk-xxx" # 硅基流动 API Key
|
||||
base_url: "https://api.siliconflow.cn/v1"
|
||||
model: "BAAI/bge-m3" # 向量模型
|
||||
dimensions: 1024 # 向量维度
|
||||
```
|
||||
|
||||
## 实现步骤
|
||||
|
||||
### 阶段一：基础设施
|
||||
1. 新增依赖并测试连接（go-libsql, google/uuid）
|
||||
2. 创建 `memory/model.go` - 数据模型
|
||||
3. 创建 `memory/db.go` - CRUD 操作
|
||||
|
||||
### 阶段二：向量服务
|
||||
4. 创建 `memory/vector.go` - 硅基流动 Embedding API
|
||||
|
||||
### 阶段三：核心逻辑
|
||||
5. 修改 `main.go` - 集成 Session
|
||||
6. 修改消息处理流程 - 存储和摘要
|
||||
7. 创建 `memory/skill.go` - 查询逻辑
|
||||
|
||||
### 阶段四：UI 和导出
|
||||
8. 添加命令支持（`/memory`, `/sessions`）
|
||||
9. 创建 `memory/export.go` - JSON 导出
|
||||
|
||||
## 依赖
|
||||
|
||||
```bash
|
||||
go get github.com/tursodatabase/go-libsql
|
||||
go get github.com/google/uuid
|
||||
go get github.com/sjzsdu/langchaingo-cn/llms/siliconflow
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **CGO 要求**：`go-libsql` 需要 CGO 启用
|
||||
2. **向量维度**：BGE-M3 默认 1024 维
|
||||
3. **摘要生成**：使用 AI 返回内容的前 N 字符作为摘要
|
||||
4. **错误处理**：向量服务失败时降级为纯文本搜索
|
||||
Reference in New Issue
Block a user