记忆系统

太虚永忆（UHMS）— 对话压缩、VFS 三级持久化、向量混合检索，让智能体越用越懂你

Crab Claw 的记忆系统不是简单的聊天历史存储——它是一套统一分层记忆系统（Unified Hierarchical Memory System），通过对话压缩、VFS 持久化、向量检索三大核心能力，让智能体跨会话记住你的偏好和上下文。

为什么需要记忆系统

跨会话持久化

记忆以 Markdown 文件持久化到磁盘，不随会话关闭而消失。下次对话自动加载相关记忆。

智能压缩

对话过长时自动压缩历史，提取关键信息写入记忆文件。既节省 token 又不丢失重要上下文。

混合检索

BM25 关键词搜索 + 向量语义搜索双通道。既能精确匹配关键词，又能理解语义相关性。

本地优先

支持本地 ONNX 嵌入模型，无需外部 API。数据完全本地化，隐私有保障。

三级存储架构

shell

┌──────────────────────────────────────────────────────────┐
│  L1: 工作记忆 (Working Memory)                            │
│      当前会话上下文窗口中的内容                              │
│      LLM 可直接访问，随会话结束清除                          │
├──────────────────────────────────────────────────────────┤
│  L2: 日志记忆 (Episodic Memory)                           │
│      memory/YYYY-MM-DD.md — 每日记忆日志                   │
│      Agent 在对话中主动写入，压缩时自动刷写                  │
├──────────────────────────────────────────────────────────┤
│  L3: 长期记忆 (Semantic Memory)                           │
│      MEMORY.md — 精选的长期记忆                            │
│      向量索引 — 语义检索入口                                │
│      VFS 持久化 — 合约、蓝图等结构化数据                     │
└──────────────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────────┐
│  L1: 工作记忆 (Working Memory)                            │
│      当前会话上下文窗口中的内容                              │
│      LLM 可直接访问，随会话结束清除                          │
├──────────────────────────────────────────────────────────┤
│  L2: 日志记忆 (Episodic Memory)                           │
│      memory/YYYY-MM-DD.md — 每日记忆日志                   │
│      Agent 在对话中主动写入，压缩时自动刷写                  │
├──────────────────────────────────────────────────────────┤
│  L3: 长期记忆 (Semantic Memory)                           │
│      MEMORY.md — 精选的长期记忆                            │
│      向量索引 — 语义检索入口                                │
│      VFS 持久化 — 合约、蓝图等结构化数据                     │
└──────────────────────────────────────────────────────────┘

文件布局

路径	说明
`memory/YYYY-MM-DD.md`	每日记忆日志（每天一个文件）
`MEMORY.md`	精选长期记忆（可选）
`memory/.cache/`	Embedding 缓存文件
`~/.crabclaw/memory/`	UHMS VFS 持久化目录

Agent 在自然对话中通过写入这些文件存储记忆。不强制格式，但鼓励结构化笔记。

压缩管道

当对话历史接近上下文窗口限制时，UHMS 自动触发压缩：

shell

对话历史增长 → 检测 token 使用率
    │
    ├─ 未超阈值 → 继续对话
    │
    └─ 超过阈值 → 触发压缩管道
        │
        ├─ 1. 静默记忆刷写（autoFlush）
        │     Agent 被提示将重要上下文写入记忆文件
        │
        ├─ 2. 观察脱敏（MaskObservations）
        │     移除冗余的工具调用结果细节
        │
        ├─ 3. 摘要生成（SummarizeMessagesWithAnchor）
        │     以锚点为中心生成结构化摘要
        │
        ├─ 4. Token 估算（EstimateTokens）
        │     确保压缩后在窗口限制内
        │
        └─ 5. 保留近期（ResolvedKeepRecent）
              保留最近 N 条消息不压缩
对话历史增长 → 检测 token 使用率
    │
    ├─ 未超阈值 → 继续对话
    │
    └─ 超过阈值 → 触发压缩管道
        │
        ├─ 1. 静默记忆刷写（autoFlush）
        │     Agent 被提示将重要上下文写入记忆文件
        │
        ├─ 2. 观察脱敏（MaskObservations）
        │     移除冗余的工具调用结果细节
        │
        ├─ 3. 摘要生成（SummarizeMessagesWithAnchor）
        │     以锚点为中心生成结构化摘要
        │
        ├─ 4. Token 估算（EstimateTokens）
        │     确保压缩后在窗口限制内
        │
        └─ 5. 保留近期（ResolvedKeepRecent）
              保留最近 N 条消息不压缩

Coder 专用压缩子系统

编程子智能体（Open Coder）执行长任务时有独立的压缩策略：

心跳驱动：每次 report_heartbeat 时检查上下文使用率
计划主轴摘要：围绕执行计划的 7 段结构化摘要模板
双重压缩防护：coderCompressed 标志位防止重复压缩
跨会话恢复：压缩后的摘要可用于恢复执行状态

向量记忆搜索

支持的 Embedding Provider

Provider	模型	说明
OpenAI	`text-embedding-3-small`	高质量，需 API Key
Google Gemini	`embedding-001`	Google 生态
Voyage AI	—	专业嵌入模型
本地 ONNX	自动下载	无需 API，完全本地
自定义	OpenAI 兼容端点	任意兼容接口

搜索工具

工具	说明
`memory_search`	语义搜索记忆文件（向量 + BM25 混合）
`memory_get`	获取特定日期的记忆条目

混合搜索

结合两种检索策略获得最佳结果：

BM25 关键词搜索：精确匹配特定术语、名称、代码片段
向量语义搜索：理解语义相关性，找到概念相近的内容
融合排序：两种结果加权合并，取最优排序

Embedding 缓存

按文件缓存到 .cache 目录
文件内容变化时自动失效重建
避免重复计算，降低 API 调用成本

配置

基础配置

json

{
  "agent": {
    "memory": {
      "autoFlush": true,
      "search": {
        "enabled": true,
        "provider": "openai"
      }
    }
  }
}
{
  "agent": {
    "memory": {
      "autoFlush": true,
      "search": {
        "enabled": true,
        "provider": "openai"
      }
    }
  }
}

本地 Embedding（零 API 依赖）

json

{
  "agent": {
    "memory": {
      "search": {
        "enabled": true,
        "provider": "local"
      }
    }
  }
}
{
  "agent": {
    "memory": {
      "search": {
        "enabled": true,
        "provider": "local"
      }
    }
  }
}

首次使用时自动下载 ONNX 模型到 ~/.crabclaw/models/，后续完全离线运行。

自定义兼容端点

json

{
  "agent": {
    "memory": {
      "search": {
        "provider": "custom",
        "apiBase": "http://localhost:8080/v1",
        "model": "my-embedding-model"
      }
    }
  }
}
{
  "agent": {
    "memory": {
      "search": {
        "provider": "custom",
        "apiBase": "http://localhost:8080/v1",
        "model": "my-embedding-model"
      }
    }
  }
}

VFS 持久化

UHMS 通过 VFS（Virtual File System）层持久化结构化数据：

合约存储：contractStore + TTL 清理
蓝图缓存：子智能体蓝图持久化
会话元数据：压缩后的会话摘要

CLI 命令

bash

# 记忆系统状态
crabclaw memory status

# 触发重新索引
crabclaw memory index

# 健康检查
crabclaw memory check

# 搜索记忆
crabclaw memory search "上次讨论的架构方案"
# 记忆系统状态
crabclaw memory status

# 触发重新索引
crabclaw memory index

# 健康检查
crabclaw memory check

# 搜索记忆
crabclaw memory search "上次讨论的架构方案"

记忆 vs 上下文

维度	记忆	上下文
生命周期	永久（磁盘文件）	会话级（随会话结束清除）
访问方式	搜索工具 / bootstrap 注入	LLM 直接可见
大小限制	磁盘空间	上下文窗口大小
更新方式	Agent 主动写入 / 压缩刷写	每轮对话自动追加

相关文档：编程子智能体 · 系统架构 · 安全沙箱