Veritas Memory

SKILL.md

---
name: veritas-memory
description: "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."
---

# 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

```markdown
新会话启动时：
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. 会话结束前（主动）:**

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

```markdown
## 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. 下次启动时（兜底）:**

```markdown
# 检查 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

| 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

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.