HxClaw/docs/memory-plan.md

# 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. **错误处理**：向量服务失败时降级为纯文本搜索