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 表

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 表

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 需启用

数据库设计

表结构

-- 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);

数据模型

// 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 中新增：

# 聊天记忆体配置
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 导出

依赖

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