Veritas Memory v4 🧠#

Conversation is ground truth. Files are cache. 部署即验证。

v1：STATE.md 被当作记忆本体，手动漏。 v2：对话即记忆，文件是自动索引。 v3（2026-06-06）：启动缺口检测。 v4（2026-06-11）：凭据索引层 + 多源扫描 + deep history retrieval。 v4.2（2026-06-11）：引入四层记忆架构，区分 stability/recceny；日志归档；部署即验证。

四层架构#

text

Layer 1 — IDENTITY    SOUL.md + IDENTITY.md   人格锚点，只读
Layer 2 — WORKING     STATE.md                当前状态，≤50行
Layer 3 — SHORT-TERM  memory/YYYY-MM-DD.md    每日日志，14 日归档
Layer 4 — LONG-TERM   MEMORY.md              精华摘要，≤100行
BONUS   — CREDS       CREDENTIALS_INDEX.md    凭据地图
BONUS   — DEEP        sessions + grep JSONL    历史检索兜底
BONUS   — DEPLOY      改代码→部署→验证        不过轮

Quick Start#

1. AGENTS.md 启动协议 v4#

markdown

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

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

text

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. Credential Layer（v4 新增）#

凭据不依赖 sync。 对话中收到任何 API Key / Token / 密码 → 本轮立即处理，不过夜。

写入流程（对话中收到凭据时）

markdown

收到凭据 → 本轮回复中立即：
1. 写入 CREDENTIALS_INDEX.md（service → key_name → location）
2. 写入目标服务器 .env 或 systemd Environment=
3. 加密存 CREDENTIALS.md.gpg（如敏感）
4. 验证连通性（curl 测试）

为什么不在会话结束时才写： 凭据是单点故障。sync 漏一次 → Key 丢失 → agent 失忆。

查询流程（需要凭据时）

markdown

需要 Key → 按顺序查：
1. CREDENTIALS_INDEX.md（最快，1 秒）
2. 目标服务器 .env（cat /opt/*/ .env）
3. systemd service（systemctl cat <service> | grep Environment）
4. 最后才反问用户

多源扫描清单：

• .env 文件（各项目目录）
• systemctl cat <service> 的 Environment= 行
• /etc/environment
• export / env 当前进程环境
• GPG 加密文件 CREDENTIALS.md.gpg

CREDENTIALS_INDEX.md 格式

markdown

# Credential Index

| Service | Key Name | Location | Status |
|---------|----------|----------|--------|
| TokenMall | TOKENMALL_API_KEY | systemd flintapi-overseas | ✅ verified |
| DeepSeek | BUILT_IN_FORGE_API_KEY | systemd flintapi-overseas | ✅ |
| Stripe | STRIPE_SECRET_KEY | systemd flintapi-overseas | ✅ |

5. Log Archiver（v4.2 新增）#

每日日志膨胀 → 定期归档。memory/ 目录超过 30 个文件时触发归档。

bash

mkdir -p memory/archive
find memory/ -maxdepth 1 -name '????-??-??.md' -mtime +14 -exec mv {} memory/archive/ \;

在 HEARTBEAT.md 或 Memory Tender 中触发，每 1-2 周运行。

6. 部署即验证（v4.2 新增）#

说修了 ≠ 部署了。 三次教训（Key 没存、C1 参数未部署、trade_direction 修了没推）。

硬规则： 改代码 → 部署到服务器 → 立刻验证 → 验证通过才算 done。不过夜、不过轮。

验证清单：

• 文件已推送到目标服务器
• 服务已重启 ( systemctl restart)
• 服务 active ( systemctl is-active)
• 关键端点返回预期值 (curl / grep)
• 参数变更已确认生效

7. Deep History Retrieval（v4.1 新增）#

sessions_history 有窗口限制。 长对话中大量 tool call 会挤掉用户消息，历史对话成黑洞。

检索优先级

markdown

需要找某条历史对话：

1. sessions_history(limit=200)                     ← 最快，但要够得着
2. 够不着 → 读 transcript 文件直接搜                  ← 兜底
   exec: grep -i "关键词" /root/.openclaw/agents/m/sessions/{sessionId}.jsonl
3. 不知道在哪个 session → spawn 子 agent 扫全部 session 文件
   subagent task: "Search all M session transcript files for [query]. Return matching messages with timestamps."

为什么 sessions_history 不够

• sessions_history 返回 N 条消息（含 tool call），200 条窗口可能只覆盖 30 条用户消息
• 今天跟 mooze 聊了 20 轮 FlintAPI，200 条 limit 只拉到今天会话，昨天的 Key 消息完全够不着
• 对话越长、tool call 越多，窗口越浅

兜底命令模板

bash

# 搜当前 session 的所有用户消息
grep '"role":"user"' /root/.openclaw/agents/m/sessions/{sessionId}.jsonl

# 搜所有 M session 文件中的关键词
grep -rl "关键词" /root/.openclaw/agents/m/sessions/*.jsonl | xargs grep -l '"role":"user"'

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

合并旧事件、清理过时记忆、交叉验证。同步更新 CREDENTIALS_INDEX.md。

Core Files#

FilePurposeWritersessions_historyGround truth memorySystem (auto)STATE.mdEvent timeline + current stateAuto-sync + gap fixMEMORY.mdCurated long-term memoryAuto-sync + Tendermemory/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 自己补。补不全再问。
7. 凭据不走 sync。 凭据类信息（API Key / Token / 密码）收到后本轮立即写入索引 + 目标服务器，不等到会话结束。
8. 查凭据走多源扫描。 .env + systemd Environment= + /etc/environment + GPG，全查完再反问。

Real-World Failures#

2026-06-06 — 缺口检测缺失#

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

2026-06-11 — 凭据索引缺失 + 历史检索黑洞#

环节发生了应该发生mooze 给 TokenMall Key✅ 存在 systemd Environment=—凭据索引写入❌ 未创建 CREDENTIALS_INDEX.md✅ 本轮立即写索引下次会话找 Key❌ sessions_history(200) 只拉到今天消息✅ 先读索引，找不到直接 grep transcript 文件回退检索❌ 不知道可以直接搜 transcript JSONL✅ v4.1：Deep History Retrieval 三步回退根因 1systemd 存了 Key 但 agent 不知道去那里找v4：凭据索引 + 多源扫描根因 2sessions_history 窗口太浅，老旧消息不可达v4.1：transcript 文件直接搜索

ClawHub Package#

text

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.

text

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.