ClawHub

Veritas Memory

Automation

Veritas Memory v3 — log-as-truth agent memory with gap detection. Conversation is ground truth, files are cache. Session auto-sync + startup gap check. Use when: agent forgets context, memory files go stale, or building cross-agent memory.

Install

openclaw skills install veritas-memory

Veritas Memory v3 🧠

Conversation is ground truth. Files are cache.

v1 问题：STATE.md 被当作记忆本体，手动维护必然漏。 v2 反转：对话即记忆，文件是自动同步的索引。 v3（2026-06-06）：v2 的 auto-sync 依赖会话结束前 spawn 子 agent。如果会话中断/超时，sync 不触发，下次启动时 STATE.md 过期。v3 加启动缺口检测——每次启动比对 STATE.md 时间戳和上次会话时间，发现缺口先补同步。

Architecture

PRIMARY:  sessions_history (last 30 messages)  ← Ground truth
INDEX:    STATE.md (auto-synced + gap-fixed)   ← Hot cache, ≤50 lines
LONG-TERM: MEMORY.md                            ← Curated, ≤100 lines
RAW:      memory/YYYY-MM-DD.md                  ← Manual notes on demand

Quick Start

1. AGENTS.md 启动协议 v3

新会话启动时：
1. sessions_history(your_last_session, limit=30) → 读对话原文
2. STATE.md 当前状态区 → 快速索引
3. 🔍 缺口检测：STATE.md 最后事件时间 < 上次会话结束时间？
   → YES → spawn 子 agent 补同步 → 完成后再继续
4. MEMORY.md → 长期上下文
5. 冲突 → 对话为准，修正 STATE.md

缺口检测逻辑（v3 核心）：

STATE_LAST_EVENT_TIME = 从 STATE.md 最后更新时间戳解析
LAST_SESSION_END_TIME = sessions_list 中上一个 session 的 endedAt

if STATE_LAST_EVENT_TIME < LAST_SESSION_END_TIME:
    # State 比对话旧 → 上次会话结束后 sync 漏了
    → spawn sub-agent 读上次会话 transcript
    → 补同步 STATE.md + MEMORY.md
    → 完成后再回答用户

这是 2026-06-06「没修好」事故的根因：上次修了 breakout-trade，sync 没触发，STATE.md 不知道。

2. 两层同步保障

A. 会话结束前（主动）:

对话中不打断写文件。会话结束前：

## Session End Auto-Sync

spawn sub-agent with:
  task: "Read this conversation transcript. Extract key changes:
    - Decisions made
    - Company/project status changes
    - System/infrastructure changes
    - New todos or completed todos
    Append to STATE.md event timeline. Update MEMORY.md if long-term facts changed."

B. 下次启动时（兜底）:

# 检查 STATE.md 最后更新时间
# 如果比 sessions_history 最后一条消息还旧 → sync 漏了
→ 先 spawn 子 agent 补同步，再继续对话

3. Context Loss Recovery（v3 新增）

当 agent 收到不完整上下文的消息时（如「没修好」「上次那个呢」「修好了没」），遵循：

  1. 先自查 — 当前 session 里是否有上一段对话？
  2. 无则补 — sessions_history(prev_session) → 读上次对话原文
  3. 不要反问 — 用户已经说了关键信息，是你没记住。反问浪费用户时间
  4. 优先修缓存 — 找到缺口后先写 STATE.md，再回答

今早事故：agent 反问「你说的是哪件事没修好？」→ 用户被迫转发告警截图。不该发生。v3 的缺口检测 + 启动协议可以防止。

4. Memory Tender（可选，每 2-3 天）

合并旧事件、清理过时记忆、交叉验证。

Core Files

FilePurposeWriter
sessions_historyGround truth memorySystem (auto)
STATE.mdEvent timeline + current stateAuto-sync + gap fix
MEMORY.mdCurated long-term memoryAuto-sync + Tender
memory/YYYY-MM-DD.mdOptional raw notesAgent (on demand)

Lessons

  1. 对话是记忆本体。 新会话先读 sessions_history，不依赖二手笔记。
  2. 不打断写文件。 手工 WAL 必然漏。自动同步比勤奋可靠。但同步可能漏，启动必须检测。
  3. 缺口检测是硬要求，不是优化。 每次启动必须比对 STATE.md 时间戳和上次会话时间。
  4. 小文件大索引。 STATE.md 保持 ≤50 行、MEMORY.md ≤100 行。信息膨胀就删旧留新。
  5. 冲突时对话赢。 文件过期了就修文件，不要用过期信息反驳对话。
  6. 丢失上下文时不要反问。 先用 sessions_history 自己补。补不全再问。

Real-World Failure (2026-06-06)

环节发生了应该发生
上次会话修了 breakout-trade✅—
会话结束 sync❌ 未触发（会话中断）✅ 写入 STATE.md
下次启动 gap 检测❌ v2 无此步骤✅ 发现缺口→补同步
用户说「没修好」❌ agent 反问「哪件事」✅ agent 已读过上次对话

ClawHub Package

veritas-memory/
  SKILL.md              ← This file
  templates/
    STATE.md            ← Template
    MEMORY.md           ← Template
    AGENTS_startup.md   ← Startup protocol snippet
  scripts/
    auto-sync.md        ← Sub-agent prompt for session-end sync
    memory-tender.md    ← Periodic maintenance prompt

Bidirectional Verification

Logs are the referee between user and agent.

Agent says X, user says Y:
  → Check sessions_history
  → Agent wrong → "You're right. I misremembered." → Fix cache
  → User wrong → "According to our conversation on [date], we said X. Want to change?"
  → Both right, different times → Clarify timeline

Never say "You're wrong." Present facts neutrally.

More in Automation