Total Recall — 自主智能体记忆

唯一一款自主监视的智能体记忆技能。

无需数据库、无需向量、无需手动保存。仅需一个 LLM 观察器，将对话压缩为优先级笔记，在笔记增长时自动合并，并恢复遗漏的内容。五层冗余，零维护。每月约 $0.00（使用免费模型）。

其他记忆技能要你“记得去记忆”，而这个技能只是“认真关注”。

架构

Layer 1: Observer (cron, 每 15-30 分钟)
    ↓ 压缩最近的消息 → observations.md
Layer 2: Reflector (当 observations > 8000 字时自动触发)
    ↓ 合并、移除已过时的信息 → 减少 40-60%
Layer 3: Session Recovery (每次 /new 或 /reset 时运行)
    ↓ 捕获 Observer 遗漏的会话
Layer 4: Reactive Watcher (inotify 守护进程，仅 Linux)
    ↓ 在 40+ 次新的 JSONL 写入后触发 Observer，冷却 5 分钟
Layer 5: Pre-compaction hook (memoryFlush)
    ↓ 在 OpenClaw 压缩上下文前紧急捕获

功能

Observer：读取最近的会话记录（JSONL），发送给 LLM，并将压缩后的观察内容（含优先级：高、中、低）追加到 observations.md 中。
Reflector：当观察内容过于庞大时自动触发，合并相关条目并丢弃过时、低优先级的条目。
Session Recovery：在会话启动时运行，检查上一轮会话是否已被捕获，如果未捕获则进行紧急观察。
Reactive Watcher：使用 inotify 监控会话目录，确保在活动高峰期比 cron 更频繁地触发 Observer。
Pre-compaction hook：在 OpenClaw 即将压缩上下文时触发，确保没有任何信息丢失。

快速开始

1. 安装技能

clawdhub install total-recall

2. 设置 API 密钥

在 .env 或 OpenClaw 配置中添加：

OPENROUTER_API_KEY=sk-or-v1-xxxxx

3. 运行设置脚本

bash skills/total-recall/scripts/setup.sh

该脚本会：

创建记忆目录结构（memory/、logs/、备份）
在 Linux（带 inotify + systemd）上安装反应式监视器服务
打印出需要手动添加的 cron 作业和智能体配置说明

4. 配置智能体加载观察内容

在智能体的工作区上下文（例如 MEMORY.md 或系统提示）中添加：

在会话启动时，读取 `memory/observations.md` 以获取跨会话上下文。

或者使用 OpenClaw 的 memoryFlush.systemPrompt 注入启动指令。

平台支持

平台	Observer + Reflector + Recovery	Reactive Watcher
Linux (Debian/Ubuntu 等)	完全支持	需安装 inotify-tools
macOS	完全支持	不支持（仅 cron）

所有核心脚本均使用可移植的 bash。stat、date 和 md5 命令通过 _compat.sh 跨平台处理。

配置

所有脚本从环境变量中读取，并带有合理默认值：

变量	默认值	描述
`OPENROUTER_API_KEY`	(必填)	用于 LLM 调用的 OpenRouter API 密钥
`MEMORY_DIR`	`$OPENCLAW_WORKSPACE/memory`	observations.md 所在目录
`SESSIONS_DIR`	`~/.openclaw/agents/main/sessions`	OpenClaw 会话记录目录
`OBSERVER_MODEL`	`stepfun/step-3.5-flash:free`	用于压缩的主要模型 (免费)
`OBSERVER_FALLBACK_MODEL`	`nvidia/nemotron-3-nano-30b-a3b:free`	当主要模型失败时的备用模型 (免费)
`OBSERVER_LOOKBACK_MIN`	`15`	回看分钟数 (白天)
`OBSERVER_MORNING_LOOKBACK_MIN`	`480`	早上 8 点前的回看分钟数
`OBSERVER_LINE_THRESHOLD`	`40`	触发反应式监视的行数阈值 (Linux)
`OBSERVER_COOLDOWN_SECS`	`300`	反应式监视触发之间的冷却时间 (Linux)
`REFLECTOR_WORD_THRESHOLD`	`8000`	触发 Reflector 的字数阈值
`REFLECTOR_MODEL`	`nvidia/nemotron-3-super-120b-a12b:free`	用于合并观察内容的模型 (免费)
`REFLECTOR_FALLBACK_MODEL`	`openrouter/hunter-alpha`	当 Reflector 模型失败时的备用模型 (免费)
`OPENCLAW_WORKSPACE`	`~/your-workspace`	工作区根目录

LLM 提供商配置

Total Recall 使用任何兼容 OpenAI 的聊天补全 API。通过设置环境变量切换提供商：

变量	默认值	描述
`LLM_BASE_URL`	`https://openrouter.ai/api/v1`	API 端点
`LLM_API_KEY`	回退到 `OPENROUTER_API_KEY`	API 密钥
`LLM_MODEL`	`deepseek/deepseek-v3.2`	使用的模型

提供商示例

# OpenRouter (默认)
export OPENROUTER_API_KEY="your-key"

# Ollama (本地)
export LLM_BASE_URL="http://localhost:11434/v1"
export LLM_API_KEY="ollama"
export LLM_MODEL="llama3.1:8b"

# Groq
export LLM_BASE_URL="https://api.groq.com/openai/v1"
export LLM_API_KEY="your-groq-key"
export LLM_MODEL="llama-3.3-70b-versatile"

创建的文件

memory/
  observations.md          # 主要的观察日志 (在启动时加载)
  observation-backups/     # Reflector 备份 (保留最近 10 个)
  .observer-last-run       # 上次 Observer 运行的时间戳
  .observer-last-hash      # 上次处理消息的去重哈希
logs/
  observer.log
  reflector.log
  session-recovery.log
  observer-watcher.log

Cron 作业

设置脚本会创建以下 OpenClaw cron 作业：

作业	调度	描述
`memory-observer`	每 15 分钟	压缩最近的对话
`memory-reflector`	每小时	如果观察内容过大则合并

Reactive Watcher (仅 Linux)

反应式监视器使用 inotifywait 检测会话活动，比单独使用 cron 更快地触发 Observer。需要安装 inotify-tools 的 Linux 系统。

# 安装 inotify-tools (Debian/Ubuntu)
sudo apt install inotify-tools

# 查看监视器状态
systemctl --user status total-recall-watcher

# 查看日志
journalctl --user -u total-recall-watcher -f

成本

使用 OpenRouter 的默认免费模型：

典型使用场景（observer + reflector）每月约 $0.00（使用免费模型）
每天约 15-30 次 cron 运行，每次处理几百个 token
所有默认模型均为免费模型

模型注意事项

脚本包含针对 API 响应中 .content 和 .reasoning 字段的防御性处理。虽然大多数模型在标准 .content 字段中返回内容，但回退到 .reasoning 字段可确保与可能使用不同响应格式的模型兼容。

工作原理 (技术细节)

Observer

查找最近修改的会话 JSONL 文件
过滤掉子代理/cron 会话
从回看窗口中提取用户 + 助手消息
使用 MD5 哈希比较进行去重
将数据发送给 LLM，附带观察提示（基于优先级的压缩）
将结果追加到 observations.md
如果观察内容超过字词阈值，触发 Reflector

Reflector

备份当前观察内容
将整个日志发送给 LLM，附带合并指令
验证输出比输入更短（健全性检查）
用合并后的版本替换观察内容
清理旧备份（保留最后 10 个）

Session Recovery

每次 /new 或 /reset 时运行
对上一个会话文件的最近几行进行哈希处理
与上一次 Observer 运行存储的哈希进行比较
如果不匹配：以恢复模式运行 Observer（4 小时回看）
回退：如果 Observer 执行失败，则提取原始消息

Reactive Watcher

使用 inotifywait 监控会话目录
仅统计主会话文件中的 JSONL 写入次数
超过 40 行后：触发 Observer（冷却 5 分钟）
检测到 cron/外部 Observer 运行时重置计数器

自定义提示词

Observer 和 Reflector 的系统提示词位于 prompts/ 目录：

prompts/observer-system.txt — 控制对话的压缩方式
prompts/reflector-system.txt — 控制观察内容的合并方式

修改这些文件以匹配您的智能体个性和优先级。

梦循环

梦循环是一个可选的夜间智能体程序，在工作时间后运行以合并 observations.md。它会归档过时的条目并添加语义钩子，以便有用的信息不会真正丢失。上下文保持精练；所有内容都能被找到。

功能

根据影响（关键 / 高 / 中 / 低 / 最低）和年限对每一条观察进行分类
归档已超过相关性阈值的条目
为每个归档条目添加语义钩子（特定关键词 + 存档引用）
验证结果，如果出现问题则自动回滚

特性

多钩子检索 — 每个归档条目有 4-5 种替代搜索表述。使用与原文不同的词语进行搜索仍能找到记忆。

置信度评分 — 每个观察都获得置信度评分（0.0-1.0）和来源类型（explicit、implicit、inference、weak、uncertain）。高置信度的条目保留更长时间；低置信度的条目更早归档。

记忆类型系统 — 7 种类型，每种类型有对应的 TTL： event（14 天）、fact（90 天）、preference（180 天）、goal（365 天）、habit（365 天）、rule（从不）、context（30 天）。以不可见的 HTML 元数据注释形式嵌入到 observations.md 中。

观察分块 — 将 3 个或更多相关观察组成的簇压缩为单个摘要条目。源观察被归档；一个分块钩子代替它们。可实现高达 75% 的 token 缩减。

重要性衰减 — 每个决策前对重要性评分按类型进行每日衰减。衰减到归档阈值以下的条目将被排队移除。衰减速率：event（-0.5/天）、fact（-0.1/天）、preference（-0.02/天）、rule/habit/goal（无衰减）。

模式提升 — 扫描最近的梦日志以寻找重复出现的主题（在 3 个或更多不同的日子出现 3 次或更多）。将提升建议写入 memory/dream-staging/ 目录，供人工审核。使用 staging-review.sh 查看列表、展示、批准或拒绝建议。context 类型从不自动提升。

设置

运行 bash skills/total-recall/scripts/setup.sh — 自动创建梦循环目录。

将夜间 cron 作业添加为完整的智能体轮次：

# Dream Cycle — nightly (3am recommended; adjust to your timezone)
# The dream cycle runs as a full agent turn — NOT as a direct bash call.
# dream-cycle.sh is a file operations helper called BY the agent, not the entry point.
#
# 0 3 * * * bash -c 'source ~/.openclaw/shared/secrets/openclaw-secrets.env \
#   && openclaw agent --agent main \
#   --message "Run the Total Recall Dream Cycle. Follow the instructions in \
# $WORKSPACE/skills/total-recall/prompts/dream-cycle-prompt.md exactly. \
# Use READ_ONLY_MODE=false and DREAM_PHASE=1." \
#   --json >> $WORKSPACE/logs/dream-cycle.log 2>&1'

使用 prompts/dream-cycle-prompt.md 作为系统提示词配置您的 cron 智能体。推荐模型：Claude Sonnet 用于 Dreamer（分析 + 决策），DeepSeek v3.2 用于 Observer（便宜、快速）。
前几个晚上以 READ_ONLY_MODE=true 开始。每次运行后检查 memory/dream-logs/，以确认它会归档哪些内容。
满意后切换到 READ_ONLY_MODE=false。

配置

变量	默认值	描述
`DREAM_TOKEN_TARGET`	`8000`	合并后 observations.md 的 token 目标数
`READ_ONLY_MODE`	`false`	设置为 `true` 以进行仅分析而不写入的试运行

文件

文件	描述
`scripts/dream-cycle.sh`	由智能体调用的 Shell 辅助脚本（非独立运行器）：预检查、归档、更新观察、写日志、写指标、验证、回滚
`prompts/dream-cycle-prompt.md`	用于夜间梦循环运行的智能体提示词
`dream-cycle/README.md`	梦循环快速参考
`schemas/observation-format.md`	扩展观察元数据格式

创建的目录

memory/
  archive/
    observations/        # 归档条目 (每晚一个 .md 文件)
    chunks/              # 分块的观察组
  dream-logs/            # 每次夜运行的报告
  dream-staging/         # 等待人工审核的模式提升建议
  .dream-backups/        # 运行前的安全备份
research/
  dream-cycle-metrics/
    daily/               # 每晚的 JSON 指标

故障排查

Observer 不运行？

检查 logs/observer.log 中的错误
确认 OPENROUTER_API_KEY 已设置且有效
确认 cron 处于活动状态：crontab -l

会话启动时未加载观察内容？

确保您的智能体启动指令包含读取 memory/observations.md
检查 MEMORY_DIR 是否指向正确的位置

Reactive watcher 未触发 (Linux)？

运行 systemctl --user status total-recall-watcher
检查是否安装了 inotify-tools：which inotifywait
查看监视器日志：journalctl --user -u total-recall-watcher -f

梦循环归档过于激进？

启用 READ_ONLY_MODE=true 并在正式使用前审查梦日志
向上调整 DREAM_TOKEN_TARGET 以减少每次运行的归档量

梦循环归档不足？

降低 DREAM_TOKEN_TARGET 以触发更激进的合并

灵感来源

本系统的灵感来源于人类记忆在睡眠期间的工作方式——海马体（观察者）捕获经验，而在睡眠巩固期间（反射器），重要的记忆得到加强，噪音被丢弃。

了解更多： Your AI Has an Attention Problem

"Get your ass to Mars." — 那么，让你的智能体记忆工作起来吧。

在你喜欢的 AI 中提问

文档