total-recall

Total Recall — 自主 Agent 记忆

唯一会自动观察的记忆技能。

没有数据库。没有向量。无需手动保存。只有一个 LLM 观察器，它会将你的对话压缩成按优先级排序的笔记，在笔记增多时进行整合，并找回任何遗漏的内容。五层冗余，零维护。（使用免费层模型时）每月约 $0.00。

其他记忆技能让你记得去记忆，而这个技能只会专心留意。

架构

Layer 1: Observer (cron, every 15-30 min)
    ↓ compresses recent messages → observations.md
Layer 2: Reflector (auto-triggered when observations > 8000 words)
    ↓ consolidates, removes superseded info → 40-60% reduction
Layer 3: Session Recovery (runs on every /new or /reset)
    ↓ catches any session the Observer missed
Layer 4: Reactive Watcher (inotify daemon, Linux only)
    ↓ triggers Observer after 40+ new JSONL writes, 5-min cooldown
Layer 5: Pre-compaction hook (memoryFlush)
    ↓ emergency capture before OpenClaw compacts context

功能

• 观察器读取最近的会话记录（JSONL），将其发送给 LLM，然后将压缩后的观察结果（带有高、中、低优先级）追加到 observations.md
• 反思器会在观察结果过多时启动，整合相关条目，并删除过时的低优先级条目
• 会话恢复在会话开始时运行，检查上一个会话是否已被记录；如果没有，则执行紧急观察
• 响应式监视器使用 inotify 监视会话目录，让高活跃时段的内容比 cron 间隔更快得到记录
• 压缩前钩子会在 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/、备份）
• 在安装了 inotify 和 systemd 的 Linux 上：安装响应式监视器服务
• 输出 cron 作业和 Agent 配置说明，供你手动添加

4. 配置 Agent 加载观察结果

将以下内容添加到 Agent 的工作区上下文中（例如 MEMORY.md 或系统提示词）：

At session startup, read `memory/observations.md` for cross-session context.

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

平台支持

平台	观察器 + 反思器 + 恢复	响应式监视器
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_MODEL	nvidia/nemotron-3-super-120b-a12b:free	用于整合观察结果的模型（免费）
REFLECTOR_FALLBACK_MODEL	openrouter/hunter-alpha	反思器模型失败时使用的备用模型（免费）
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 (default)
export OPENROUTER_API_KEY="your-key"

# Ollama (local)
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          # The main observation log (loaded at startup)
  observation-backups/     # Reflector backups (last 10 kept)
  .observer-last-run       # Timestamp of last observer run
  .observer-last-hash      # Dedup hash of last processed messages
logs/
  observer.log
  reflector.log
  session-recovery.log
  observer-watcher.log

定时任务

设置脚本会创建以下 OpenClaw 定时任务：

任务	时间安排	描述
memory-observer	每 15 分钟	压缩近期对话
memory-reflector	每小时	如果观察记录较长，则进行整合

响应式监视器（仅限 Linux）

响应式监视器使用 inotifywait 检测会话活动，并比单独使用定时任务更快地触发观察器。需要安装了 inotify-tools 的 Linux 系统。

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

# Check watcher status
systemctl --user status total-recall-watcher

# View logs
journalctl --user -u total-recall-watcher -f

费用

使用 OpenRouter 提供的默认免费模型：

• 典型用量（观察器 + 反思器）约为 0.00 美元/月（使用免费层级模型）
• 每天约运行 15-30 次定时任务，每次处理几百个 token
• 所有默认模型均为免费层级模型

模型说明

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

工作原理（技术说明）

观察器

1. 查找最近修改的会话 JSONL 文件
2. 过滤掉子 Agent 和定时任务会话
3. 提取回溯时间范围内的用户和助手消息
4. 使用 MD5 哈希比较进行去重
5. 使用观察器提示词（基于优先级压缩）发送给大模型
6. 将结果追加到 observations.md
7. 如果观察记录超过字数阈值，则触发反思器

反思器

1. 备份当前观察记录
2. 将整个日志连同整合指令发送给大模型
3. 验证输出是否比输入更短（合理性检查）
4. 用整合后的版本替换观察记录
5. 清理旧备份（保留最近 10 个）

会话恢复

1. 在每次 /new 或 /reset 时运行
2. 对上一个会话文件的近期行进行哈希处理
3. 与上次运行观察器时存储的哈希进行比较
4. 如果不匹配：以恢复模式运行观察器（回溯 4 小时）
5. 回退方案：如果观察器失败，则直接提取原始消息

响应式监视器

1. 使用 inotifywait 监视会话目录
2. 仅统计主会话文件的 JSONL 写入次数
3. 超过 40 行后：触发观察器（冷却 5 分钟）
4. 检测到定时任务或外部观察器运行时重置计数器

自定义提示词

观察器和反思器的系统提示词位于 prompts/：

• prompts/observer-system.txt — 控制如何压缩对话
• prompts/reflector-system.txt — 控制如何整合观察记录

编辑这些文件，以符合你的 Agent 个性和优先事项。

---

梦境周期

梦境周期是一个可选的夜间 Agent，会在非工作时间运行，以整合 observations.md。它会归档过时条目，并添加语义钩子，确保有用信息不会真正丢失。上下文保持精简，同时所有内容仍可查找。

功能

• 按影响程度（关键 / 高 / 中 / 低 / 最低）和时间对每条观察记录进行分类
• 归档已超过相关性阈值的条目
• 为每个归档条目添加语义钩子（特定关键词 + 归档引用）
• 验证结果，并在出现问题时自动回滚

功能

多钩子检索 — 每个归档条目有 4-5 种替代搜索措辞。即使搜索时使用的词语与原文不同，也能找到这条记忆。

置信度评分 — 每条观察都有一个置信度分数（0.0-1.0）和来源类型（explicit、implicit、inference、weak、uncertain）。高置信度条目会保留更久；低置信度条目会更早归档。

记忆类型系统 — 包含 7 种类型，并为每种类型设置 TTL：event（14d）、fact（90d）、preference（180d）、goal（365d）、habit（365d）、rule（永不过期）、context（30d）。这些信息以不可见的 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 类型永远不会自动提升。

设置

1. 运行 bash skills/total-recall/scripts/setup.sh — 自动创建 Dream Cycle 目录。

2. 将夜间 cron 任务添加为完整的 Agent 轮次：

   # 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'
   

3. 使用 prompts/dream-cycle-prompt.md 作为系统提示词来配置 cron Agent。推荐模型：Dreamer 使用 Claude Sonnet（分析 + 决策），Observer 使用 DeepSeek v3.2（低成本、速度快）。

4. 前几个夜晚先设置 READ_ONLY_MODE=true。每次运行后检查 memory/dream-logs/，确认它原本会归档哪些内容。

5. 确认无误后，将 READ_ONLY_MODE=false。

配置

变量	默认值	描述
DREAM_TOKEN_TARGET	8000	整合后 observations.md 的 token 目标
READ_ONLY_MODE	false	设为 true 可进行试运行分析，不写入任何内容

文件

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

创建的目录

memory/
  archive/
    observations/        # Archived items (one .md file per night)
    chunks/              # Chunked observation groups
  dream-logs/            # Nightly run reports
  dream-staging/         # Pattern promotion proposals awaiting human review
  .dream-backups/        # Pre-run safety backups
research/
  dream-cycle-metrics/
    daily/               # JSON metrics per night

---

故障排除

Observer 未运行？

• 检查 logs/observer.log 中的错误
• 确认已设置有效的 OPENROUTER_API_KEY
• 确认 cron 已启用：crontab -l

会话开始时未加载观察？

• 确保 Agent 的启动说明中包含读取 memory/observations.md
• 检查 MEMORY_DIR 是否指向正确位置

响应式监视器未触发（Linux）？

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

Dream Cycle 归档过于激进？

• 启用 READ_ONLY_MODE=true，并在正式启用前检查梦境日志
• 调高 DREAM_TOKEN_TARGET，以减少每次运行的归档量

Dream Cycle 归档不足？

• 调低 DREAM_TOKEN_TARGET，以触发更激进的整合

---

灵感来源

该系统的灵感来自人类睡眠时的记忆运作方式——海马体（观察者）记录经历，而在睡眠巩固（反思者）过程中，重要记忆得到强化，噪声则被丢弃。

了解更多：你的 AI 有注意力问题

“滚去火星。”——好吧，让你的 Agent 的记忆发挥作用吧。