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 收到不完整上下文的消息时（如「没修好」「上次那个呢」「修好了没」），遵循：
- 先自查 — 当前 session 里是否有上一段对话？
- 无则补 — sessions_history(prev_session) → 读上次对话原文
- 不要反问 — 用户已经说了关键信息，是你没记住。反问浪费用户时间
- 优先修缓存 — 找到缺口后先写 STATE.md，再回答
> 今早事故：agent 反问「你说的是哪件事没修好？」→ 用户被迫转发告警截图。不该发生。v3 的缺口检测 + 启动协议可以防止。
4. Memory Tender（可选，每 2-3 天）
合并旧事件、清理过时记忆、交叉验证。
Core Files
| File | Purpose | Writer |
|---|---|---|
sessions_history |
Ground truth memory | System (auto) |
STATE.md |
Event timeline + current state | Auto-sync + gap fix |
MEMORY.md |
Curated long-term memory | Auto-sync + Tender |
memory/YYYY-MM-DD.md |
Optional raw notes | Agent (on demand) |
Lessons
- 对话是记忆本体。 新会话先读 sessions_history，不依赖二手笔记。
- 不打断写文件。 手工 WAL 必然漏。自动同步比勤奋可靠。但同步可能漏，启动必须检测。
- 缺口检测是硬要求，不是优化。 每次启动必须比对 STATE.md 时间戳和上次会话时间。
- 小文件大索引。 STATE.md 保持 ≤50 行、MEMORY.md ≤100 行。信息膨胀就删旧留新。
- 冲突时对话赢。 文件过期了就修文件，不要用过期信息反驳对话。
- 丢失上下文时不要反问。 先用 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.
