Agent Memento v0.2 — Complete Skill Specification
---
name: agent-memento
description: Tick-Driven Autonomous Production Factory for LLMs. A framework for long-running agents using Cron/Heartbeats and physical Markdown checklists to prevent OOM and context decay.
metadata: {"clawdbot":{"emoji":"🧠","requires":{"bins":["bash","openclaw"],"env":[]}}}
---
# Agent Memento v0.2 (Tick-Driven Autonomous Execution)
> "Don't build AI that tries to remember everything. Build systems that make AI read the blueprint anew every 5 minutes."
当我们在聊天框里让大模型"写一个游戏"时，开头总是美好的。但随着代码超过 2000 行，模型开始：
- **失忆症 (Amnesia)**：忘记了自己定义的接口，开始凭空捏造。
- **幻觉重构 (Hallucination)**：自信满满地输出一堆根本没有跑过的"完美"代码。
- **上下文核爆 (Resource Overload)**：为了修一个小 Bug，强行覆盖整个大文件，导致内存耗尽 (OOM)。
**核心原则：把"全知全能的超级 Agent"降级为无数个"只有 5 分钟记忆的、无情的 Tick 机器"。**
---
## Quick Start (30 秒上手)
1. 初始化项目：
```bash
bash skills/agent-memento/scripts/init_memento.sh MyProject
- 在主对话中让 Architect 填写
MASTER_PLAN.md和PROJECT_MAP.md - 启动自动执行：
crontab -e # 添加：*/5 * * * * /path/to/MyProject/scripts/memento_tick.sh - （可选）启动 Dashboard 看板监控：
bash scripts/dashboard.sh - 去刷手机。回来看 Dashboard 或
docs/TICK_STATUS.md查看进度。
一、系统架构总览
┌─────────────────────────────────────────────────────────┐
│ Human (You) │
│ Discord / 飞书 / Dashboard Panel │
└──────────────┬──────────────────────────┬───────────────┘
│ 自然语言交互 │ 面板批注/干预
▼ ▼
┌─────────────────────────────────────────────────────────┐
│ Main Agent (Architect) │
│ LLM 本体 · 长对话 Session │
│ │
│ 职责： │
│ - 与人类讨论需求，翻译为结构化任务 │
│ - 编辑 MASTER_PLAN.md（增/删/改/重排任务） │
│ - 编辑 PROJECT_MAP.md（维护项目认知地图） │
│ - 读取 TICK_STATUS.md 和 Dashboard 批注 │
│ - 根据反馈调整计划（自主决策 or 请示人类） │
└──────────────┬──────────────────────────────────────────┘
│ 写入物理文件
▼
┌─────────────────────────────────────────────────────────┐
│ Physical State Layer (磁盘) │
│ │
│ docs/MASTER_PLAN.md ← 唯一真相源，结构化任务清单 │
│ docs/PROJECT_MAP.md ← 项目认知地图 / 文件索引 │
│ docs/TICK_STATUS.md ← Tick 执行状态流水账 │
│ docs/HUMAN_NOTES.md ← 人类批注通道（面板写入） │
│ logs/tick_*.log ← 每个 Tick 的完整执行日志 │
└──────────────┬──────────────────────────────────────────┘
│ 读取（每次从零开始）
▼
┌─────────────────────────────────────────────────────────┐
│ Tick Worker (Bricklayer) │
│ Cron 唤醒 · 短命进程 · 无状态 · 无情 │
│ │
│ 生命周期： │
│ 1. 醒来 → 读 MASTER_PLAN.md │
│ 2. 找到当前可执行任务 │
│ 3. 读 PROJECT_MAP.md 确定上下文范围 │
│ 4. 读 HUMAN_NOTES.md 检查人类批注 │
│ 5. 执行任务 → 物理验证 │
│ 6. 写结果到 TICK_STATUS.md │
│ 7. 成功则标 [x]，失败则记录 → 死亡 │
│ 8. 自动 git commit │
└─────────────────────────────────────────────────────────┘
二、The Methodology：三层智能分工
Layer 1：人类（方向盘）
- 在 Discord/飞书/Dashboard 中用自然语言描述需求和反馈
- 通过 Dashboard 面板随时插入批注、暂停/恢复流水线
- 不需要逐条审核——只在 Agent 请求帮助或自己想介入时参与
Layer 2：Architect（主 Agent / 翻译官）
- 与人类的主对话 Session
- 将模糊需求翻译为
MASTER_PLAN.md中的结构化任务 - 持续维护
PROJECT_MAP.md（项目认知地图） - 监控
TICK_STATUS.md，根据执行情况自主调整计划 - 遇到阻塞性决策时才请示人类
Layer 3：Tick Worker（子 Agent / 泥瓦匠）
- Cron 唤醒的短命进程，每次从零启动
- 绝对服从
MASTER_PLAN.md，不做创造性决策 - 执行 → 验证 → 汇报 → 死亡
三、物理状态文件规范
3.1 MASTER_PLAN.md — 唯一真相源
# MASTER_PLAN: <ProjectName>
## Meta
- created: 2025-01-15
- last_architect_edit: 2025-01-15T14:30:00
- tick_mode: auto <!-- auto | paused | stopped -->
- max_retries: 3 <!-- 单任务最大重试次数 -->
- max_tasks_per_tick: 2 <!-- 快任务时允许单 Tick 连续处理上限 -->
- max_diff_lines: 200 <!-- diff size guard 阈值 -->
- stale_lock_timeout: 15min <!-- [~] 僵尸锁重置阈值 -->
- circuit_breaker_threshold: 5 <!-- 连续失败多少次触发熔断 -->
- clean_strategy: git-clean <!-- 三阶段防爆清理机制 -->
- clean_ignore: .memento_cleanignore
- status_max_entries: 50 <!-- TICK_STATUS.md 最大条目数，超出自动归档 -->
- status_archive_dir: logs/status_archive/
- total_ticks: 0 <!-- 自动递增的 Tick 计数器 -->
- total_tasks: 15 <!-- 自动维护 -->
- completed_tasks: 0 <!-- 自动维护 -->
---
## Phase 1: Foundation
<!-- parallel: true -->
<!-- depends: none -->
- [ ] `T-101` [MODULE:database] Setup PostgreSQL schema
- verify: `cd src && npm test -- --grep "db-schema" && echo PASS`
- context_files: [src/db/schema.ts, src/db/migrations/]
- guard_files: [src/auth/*]
- estimate: 5min
- retries: 0
- [ ] `T-102` [MODULE:auth] Implement JWT token generation
- verify: `cd src && npm test -- --grep "jwt" && echo PASS`
- context_files: [src/auth/jwt.ts, tests/auth/jwt.test.ts]
- guard_files: [src/db/*]
- estimate: 5min
- retries: 0
## Phase 2: Integration
<!-- parallel: false -->
<!-- depends: Phase 1 -->
- [ ] `T-201` [MODULE:auth] Connect auth middleware to database
- verify: `cd src && npm run test:integration && echo PASS`
- context_files: [src/auth/middleware.ts, src/db/queries.ts]
- guard_files: [src/db/schema.ts]
- estimate: 10min
- retries: 0
## Phase 3: Polish
<!-- parallel: true -->
<!-- depends: Phase 2 -->
- [ ] `T-301` [MODULE:docs] Generate API documentation
- verify: `test -f docs/api.md && echo PASS`
- context_files: [src/routes/*.ts]
- guard_files: []
- estimate: 3min
- retries: 0
任务字段说明：
| 字段 | 必须 | 说明 |
|---|---|---|
T-XXX | ✅ | 任务唯一 ID，用于日志追踪和跨文件引用 |
[MODULE:xxx] | ✅ | 模块标签，帮助 Worker 理解领域边界 |
verify | ✅ | 验收命令，Exit Code 0 = 通过。没有这个字段，任务不合法 |
context_files | ✅ | Worker 允许加载的文件白名单，防止上下文爆炸 |
guard_files | 推荐 | 禁止修改的文件列表，硬约束 |
estimate | 推荐 | 预估耗时，用于 Tick 调度决策 |
retries | 自动 | 由 Tick Worker 自动递增，Architect 可重置 |
任务状态标记：
| 标记 | 含义 |
|---|---|
[ ] | 待执行 |
[x] | 已完成（verify 通过） |
[!] | 已阻塞（超过 max_retries） |
[~] | 执行中（Tick Worker 正在处理，防止并发冲突） |
[-] | 已跳过（Architect 主动标记为不需要） |
Phase 级元数据：
| 字段 | 说明 |
|---|---|
parallel: true/false | 该 Phase 内的任务是否可并发执行 |
depends: Phase X / none | Phase 级前置依赖 |
3.2 PROJECT_MAP.md — 项目认知地图
Worker 的 GPS。不读全部源码，先读地图，再按
context_files精准加载。
# PROJECT MAP: <ProjectName>
## Architecture Overview
Single-page game using Canvas API. No framework. Vanilla TypeScript.
## Module Registry
### [MODULE:database]
- Purpose: PostgreSQL connection and schema management
- Entry: src/db/index.ts
- Key interfaces: `DbConnection`, `UserRecord`, `SessionRecord`
- Notes: Uses connection pooling via pg-pool
### [MODULE:auth]
- Purpose: JWT-based authentication
- Entry: src/auth/index.ts
- Key interfaces: `AuthToken`, `AuthMiddleware`
- Dependencies: [MODULE:database]
- Notes: Tokens expire in 24h, refresh flow not yet implemented
### [MODULE:routes]
- Purpose: Express route handlers
- Entry: src/routes/index.ts
- Dependencies: [MODULE:auth], [MODULE:database]
## File Tree (auto-maintained)
<!-- Architect 应在项目结构变动时更新此区块 -->
src/
├── db/
│ ├── index.ts # DB connection pool
│ ├── schema.ts # Table definitions
│ └── migrations/ # SQL migration files
├── auth/
│ ├── index.ts # Auth module entry
│ ├── jwt.ts # Token generation/validation
│ └── middleware.ts # Express middleware
└── routes/
├── index.ts # Route registry
└── users.ts # User CRUD endpoints
## Conventions
- All tests in `tests/` mirror `src/` structure
- Config via environment variables (see .env.example)
- Error handling: all async handlers wrapped in try/catch, errors go to src/utils/errors.ts
维护规则：
- Architect 在创建/调整计划时同步更新
- Tick Worker 只读不写 PROJECT_MAP.md
- 如果 Worker 发现 MAP 与实际不符，在 TICK_STATUS.md 中报告，由 Architect 修正
3.3 TICK_STATUS.md — 执行状态流水账
# TICK STATUS LOG
---
## [2025-01-15T14:35:00] Tick #012
- **Task**: T-101 [MODULE:database] Setup PostgreSQL schema
- **Status**: ✅ SUCCESS
- **Verify Output**: `PASS` (exit code 0)
- **Duration**: 2m18s
- **Files Modified**: src/db/schema.ts (+45 -0), src/db/migrations/001_init.sql (+23 -0)
- **Diff Size**: 68 lines
- **Git Commit**: `a3f7b2c` — "memento: complete T-101 database schema setup"
---
## [2025-01-15T14:35:00] Tick #012 (continued, tasks_this_tick: 2/2)
- **Task**: T-102 [MODULE:auth] Implement JWT token generation
- **Status**: ✅ SUCCESS
- **Verify Output**: `PASS` (exit code 0)
- **Duration**: 3m41s
- **Files Modified**: src/auth/jwt.ts (+67 -0), tests/auth/jwt.test.ts (+34 -0)
- **Diff Size**: 101 lines
- **Git Commit**: `b8e2d1f` — "memento: complete T-102 JWT token generation"
---
## [2025-01-15T14:40:00] Tick #013
- **Task**: T-201 [MODULE:auth] Connect auth middleware to database
- **Status**: ❌ FAILED (retry 2/3)
- **Verify Output**: `TypeError: pool.query is not a function` (exit code 1)
- **Duration**: 4m52s
- **Error Analysis**: DB module exports `pool` but middleware imports `connection`. Interface mismatch.
- **Files Modified**: (rolled back)
- **Git Commit**: (none — rollback)
---
## [2025-01-15T14:45:00] Tick #014
- **Task**: T-201 [MODULE:auth] Connect auth middleware to database
- **Status**: 🚫 BLOCKED (retry 3/3 — max_retries exceeded)
- **Verify Output**: Same error as Tick #013
- **Error Analysis**: Recurring interface mismatch. Likely needs Architect to update MODULE:database exports or redefine task scope.
- **Escalation**: ⚠️ NEEDS ARCHITECT ATTENTION
- **Files Modified**: (rolled back)
---
3.4 HUMAN_NOTES.md — 人类批注通道
Dashboard 面板写入此文件。Tick Worker 每次启动时检查。Architect 也会读取。
# HUMAN NOTES
<!-- 格式：每条批注带时间戳和目标（global / 具体 Task ID） -->
<!-- Worker 执行完相关批注后，将 [NOTE] 改为 [NOTE:READ] -->
<!-- Architect 处理完后可归档到底部的 Archive 区 -->
## Active Notes
### [NOTE] 2025-01-15T15:00:00 → T-201
改用 Redis 做 session 存储而不是 PostgreSQL。连接配置参考项目根目录的 redis.conf。
### [NOTE] 2025-01-15T15:10:00 → global
暂停 Phase 3 的所有任务，等 Phase 2 全部稳定再说。
### [NOTE:READ] 2025-01-15T14:00:00 → T-102
JWT secret 从环境变量 `JWT_SECRET` 读取，别硬编码。
---
## Archive
<!-- Architect 把已处理的批注移到这里 -->
四、Tick 调度引擎规范
4.1 任务拾取算法
Tick Worker 醒来后执行以下逻辑：
1. 读取 MASTER_PLAN.md 的 Meta 区
- 如果 tick_mode != "auto"，写一行 "Tick skipped: mode={mode}" 到 TICK_STATUS.md，退出
2. 读取 HUMAN_NOTES.md
- 缓存所有 [NOTE]（非 [NOTE:READ]）条目，按 target 分组备用
3. 按 Phase 顺序扫描：
FOR each Phase:
a. 检查 depends 条件
- 依赖的 Phase 内是否所有任务都是 [x] 或 [-]？
- 如果有 [ ] 或 [~] 或 [!]，则该 Phase 不可进入，跳过
b. 在当前 Phase 内扫描任务：
- 跳过 [x] [!] [-] [~]
- 对于 [ ]：检查 retries < max_retries
- 如果 parallel: false，只取第一个符合条件的 [ ]
- 如果 parallel: true，取第一个符合条件的 [ ]（单 Worker 场景）
c. 找到目标任务后，break
4. 如果没有找到任何可执行任务：
- 检查是否所有任务都是 [x] 或 [-] → 写 "🎉 ALL TASKS COMPLETE" 到 TICK_STATUS.md
- 检查是否存在 [!] 阻塞 → 写 "⚠️ PIPELINE BLOCKED" 到 TICK_STATUS.md
- 退出
5. 将目标任务标记为 [~]（执行中）
6. 执行任务（详见 4.2）
7. tasks_completed_this_tick++
如果 tasks_completed_this_tick < max_tasks_per_tick 且剩余任务 estimate 合理：
回到步骤 3 继续拾取
否则退出
4.2 单任务执行流程
1. 读取任务的 context_files 列表
- 通过 PROJECT_MAP.md 理解模块上下文
- 加载 context_files 中声明的文件内容
- 检查是否有针对该 Task ID 的 HUMAN_NOTES，如有，纳入上下文
2. 执行实际工作
- 遵循铁血纪律（见第五节）
- 生成精确 diff，不做全文件覆写
3. 运行 guard_files 检查
- diff 中是否触及了 guard_files 列表中的文件？
- 如果是 → 自动回滚 → 标记失败 → 原因写 "guard file violation"
4. 运行 diff size 检查
- 单次修改是否超过 200 行？（可配置）
- 如果是 → 自动回滚 → 标记失败 → 原因写 "diff too large, possible full-file rewrite"
5. 运行 verify 命令
- 捕获 stdout/stderr 和 exit code
- Exit Code 0 → SUCCESS
- Exit Code != 0 → FAILED
6. 写结果到 TICK_STATUS.md
7. 如果 SUCCESS：
- 任务标记 [ ] → [x]
- retries 保持不变
- git add + git commit（message 格式：`memento: complete {TASK_ID} {简述}`）
8. 如果 FAILED：
- 回滚所有文件修改（git checkout 或备份恢复）
- retries += 1
- 任务保持 [ ]，清除 [~]
- 如果 retries >= max_retries：
- 标记 [!]
- TICK_STATUS 中添加 "⚠️ NEEDS ARCHITECT ATTENTION"
4.3 并发安全
当 parallel Phase 中可能有多个 Worker 并行时（高级场景）：
[~]标记充当简易锁 —— Worker 拾取任务时先标[~]，其他 Worker 看到[~]就跳过- 如果检测到
[~]标记超过 15 分钟未更新（Worker 可能崩溃），将其重置为[ ] - 在 MVP 阶段，建议单 Worker 串行执行，并发作为未来扩展
五、铁血纪律 (Execution Sandbox)
作为一个被 Memento 唤醒的 Tick Worker，你必须遵循：
纪律 1：防爆底线 (Surgical Edits Only)
- ❌ 严禁输出完整文件内容要求覆写
- ✅ 必须通过精准定位工具进行增量修改
- 硬约束：diff size guard 会物理阻断超大修改
纪律 2：拒绝脑内验算 (Evidence-Based Audit)
- ❌ 不许在脑中模拟运行然后宣称"应该没问题"
- ✅ 跑 verify 命令看真实退出码
- 没有
Exit Code 0，不许标[x]
纪律 3：不要静默空转 (No Silent Ghosting)
- ❌ 遇到问题不许沉默退出
- ✅ 把死亡原因、错误日志、分析完整写入
TICK_STATUS.md - 卡死了就大声喊出来，让 Architect 看到
纪律 4：恪守边界 (Stay in Your Lane)
- ❌ 不许修改 guard_files 中的文件
- ❌ 不许修改 MASTER_PLAN.md 的任务定义（只能改 checkbox 状态和 retries）
- ❌ 不许修改 PROJECT_MAP.md
- ✅ 只能读写 context_files 中声明的文件 + TICK_STATUS.md
纪律 5：原子提交 (Atomic Commits)
- 每完成一个任务，立即
git commit - 每失败一个任务，立即
git checkout回滚 - 确保任意时刻
git log都是干净的、可追溯的
六、Dashboard 面板设计
6.1 设计理念
Dashboard 是人类与 Memento 流水线之间的异步交互界面。不是实时聊天，而是留言板 + 监控台。人类不需要一直盯着，但打开就能在 5 秒内知道一切。
6.2 面板布局
┌─────────────────────────────────────────────────────────────┐
│ 🧠 Agent Memento Dashboard [ProjectName] │
│ Status: ● RUNNING Uptime: 2h 35m Next tick: 2m 14s │
│ ┌──────────────────┐ ┌──────────────────────────────────┐ │
│ │ Controls │ │ Progress │ │
│ │ │ │ │ │
│ │ [▶ Resume] │ │ ████████████░░░░░░░░░ 23/47 │ │
│ │ [⏸ Pause ] │ │ Phase 1 ████████████ 100% │ │
│ │ [⏹ Stop ] │ │ Phase 2 ████████░░░░ 67% │ │
│ │ │ │ Phase 3 ░░░░░░░░░░░░ 0% │ │
│ │ Tick interval: │ │ │ │
│ │ [5] min ▼ │ │ Blocked: 2 ⚠️ │ │
│ │ │ │ Est. remaining: ~1h 20m │ │
│ └──────────────────┘ └──────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────┤
│ │ Task List Filter: All │
│ │ │
│ │ ✅ T-101 [database] Setup PostgreSQL schema 2m18s │
│ │ ✅ T-102 [auth] JWT token generation 3m41s │
│ │ 🚫 T-201 [auth] Connect auth to DB BLOCKED │
│ │ └─ retries: 3/3 · "Interface mismatch" │
│ │ └─ 💬 [Add Note] │
│ │ ⬜ T-202 [auth] Password hashing waiting │
│ │ ⬜ T-301 [docs] Generate API docs Phase 3 │
│ │ │
│ └──────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────────┤
│ │ Tick Timeline Latest first │
│ │ │
│ │ 14:45 Tick #014 · T-201 · 🚫 BLOCKED │
│ │ │ "Interface mismatch — needs Architect attention" │
│ │ │ [View Full Log] │
│ │ │ │
│ │ 14:40 Tick #013 · T-201 · ❌ FAILED (retry 2/3) │
│ │ │ "TypeError: pool.query is not a function" │
│ │ │ [View Full Log] │
│ │ │ │
│ │ 14:35 Tick #012 · T-101 + T-102 · ✅✅ │
│ │ │ 2 tasks completed in 5m59s │
│ │ │ [View Full Log] [View Diff] │
│ │ │
│ └──────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────────┤
│ │ 📝 Notes │
│ │ │
│ │ ┌─────────────────────────────────────────────────────┐ │
│ │ │ Target: [T-201 ▼] or [global ▼] │ │
│ │ │ │ │
│ │ │ 改用 Redis 做 session 存储，连接配置见 redis.conf │ │
│ │ │ │ │
│ │ │ [Send Note 📤] │ │
│ │ └─────────────────────────────────────────────────────┘ │
│ │ │
│ │ Active Notes: │
│ │ • 15:10 → global: "暂停 Phase 3..." ⏳ pending │
│ │ • 15:00 → T-201: "改用 Redis..." ⏳ pending │
│ │ • 14:00 → T-102: "JWT_SECRET 环境变量..." ✅ read │
│ │ │
│ └──────────────────────────────────────────────────────────┘
└─────────────────────────────────────────────────────────────┘
6.3 面板功能规范
控制区 (Controls)
| 操作 | 行为 |
|---|---|
| Resume | 将 MASTER_PLAN.md 的 tick_mode 改为 auto |
| Pause | 将 tick_mode 改为 paused（当前 Tick 执行完后停止） |
| Stop | 将 tick_mode 改为 stopped（建议同时移除 crontab） |
| Tick interval | 修改 crontab 的执行频率 |
进度区 (Progress)
- 数据源：解析
MASTER_PLAN.md的所有 checkbox 状态 - 实时计算各 Phase 完成百分比
- 基于已完成任务的平均耗时 × 剩余任务数，估算剩余时间
任务列表 (Task List)
- 数据源：
MASTER_PLAN.md - 每个任务可展开查看：最近一次执行结果、错误信息、重试次数
- 支持过滤：All / Pending / Completed / Blocked
- 每个任务旁有
[Add Note]按钮，快速针对该任务添加批注 - 支持手动操作：
- 对
[!]任务点击[Reset Retries]→ 将 retries 重置为 0，状态改回[ ] - 对任务点击
[Skip]→ 标记为[-]
- 对
时间线 (Tick Timeline)
- 数据源：
TICK_STATUS.md - 倒序展示每个 Tick 的执行摘要
- 可展开查看完整日志（链接到
logs/tick_*.log） - 可查看该 Tick 的 Git diff
批注区 (Notes)
- 写入目标：
HUMAN_NOTES.md - 支持选择 target（global 或具体 Task ID）
- 显示所有 Active Notes 及其状态（pending / read）
- Read 后的 notes 自动折叠但不删除
6.4 面板技术建议
- 轻量优先：纯静态页面 + 文件系统轮询（每 5~10s 读取 Markdown 文件）即可
- 数据层：直接 parse Markdown 文件，不需要数据库
- 可选方案 A：本地 HTTP server（Python/Node），serve 一个 SPA，通过 API 读写 Markdown 文件
- 可选方案 B：Terminal UI（blessed/ink），不离开终端
七、错误恢复与自愈机制
7.1 单任务失败 → 自动重试
失败 → retries++ → 保持 [ ] → 下个 Tick 重试
↓
retries >= max_retries
↓
标记 [!] → 写入 TICK_STATUS "NEEDS ARCHITECT ATTENTION"
↓
跳过该任务，继续执行后续可执行任务
7.2 Phase 阻塞 → 智能跳转
Phase 2 中 T-201 被标记 [!]
↓
Phase 2 depends 未完全满足（存在非 [x]/[-] 的任务）
↓
Phase 3 无法启动
↓
如果 Phase 2 中还有其他 [ ] 任务 → 继续执行它们
如果 Phase 2 所有任务都是 [x]/[-]/[!] → 整条流水线 BLOCKED
↓
TICK_STATUS: "⚠️ PIPELINE BLOCKED — Phase 2 has unresolved [!] tasks"
7.3 Worker 崩溃 → 防腐检测
- 如果
[~]标记存在超过 15 分钟（可配置），下一个 Tick Worker 将：- 重置该任务为
[ ] - 在 TICK_STATUS 中记录 "Stale [~] detected on {TASK_ID}, reset to [ ]"
- 如果存在未提交的文件修改，执行
git checkout清理
- 重置该任务为
7.4 全局熔断
在以下情况下自动暂停流水线（tick_mode → paused）：
- 连续 5 个 Tick 全部失败（无一次 SUCCESS）
- 阻塞任务数超过总任务数的 30%
- 磁盘空间不足 / git 操作异常
在 TICK_STATUS 中写入：🔴 CIRCUIT BREAKER TRIGGERED — reason: {reason}
八、Architect 工作规范
当 Main Agent 处于 Architect 态时（与人类直接对话的 Session 中），遵循以下规范：
8.1 创建计划
- 与人类讨论项目需求，理解全貌
- 设计模块划分，写入
PROJECT_MAP.md - 将需求分解为原子任务，写入
MASTER_PLAN.md - 每个任务必须有
verify命令 —— 没有验证命令的任务不配存在 - 合理划分 Phase，声明 parallel 和 depends
8.2 监控与调整
- 定期读取
TICK_STATUS.md（可由人类触发，或在对话中主动查看） - 对于
[!]阻塞任务：- 分析失败原因
- 修改任务定义（调整 verify、context_files、拆分子任务）
- 或修改 PROJECT_MAP（更新接口定义）
- 重置 retries 为 0，状态改回
[ ]
- 对于
HUMAN_NOTES.md中的批注：- 读取并理解
- 将批注转化为 MASTER_PLAN 的具体修改
- 处理完后归档
8.3 计划变更原则
- 新增任务：追加到合适的 Phase，保持 ID 唯一
- 删除任务：标记
[-]并注释原因，不要真的删掉行 - 拆分任务：将原任务标记
[-] (拆分为 T-XXX, T-XXY)，新增子任务 - 重排 Phase：更新 depends 关系，确保 DAG 无环
九、初始化与部署
9.1 初始化命令
bash skills/agent-memento/scripts/init_memento.sh <ProjectName>
该脚本执行：
- 在项目目录下创建
docs/目录 - 生成
MASTER_PLAN.md模板（含 Meta 区和示例 Phase） - 生成
PROJECT_MAP.md模板 - 生成
TICK_STATUS.md（空） - 生成
HUMAN_NOTES.md（空） - 创建
logs/目录 - 生成
scripts/memento_tick.sh—— Tick Worker 的入口脚本 - 生成
.memento_ignore（排除node_modules/,.git/,logs/等） - 生成
scripts/tick_worker_system_prompt.md—— 注入给 Worker 的全套纪律法则和 Output 规范。 - 生成
.memento_cleanignore（保护node_modules/,.env,vendor/等） - 输出提示：“请将以下行添加到 crontab 以启动自动执行”
9.1.1 Tick Worker System Prompt 模板 (tick_worker_system_prompt.md)
以下是 init_memento.sh 应生成的 scripts/tick_worker_system_prompt.md 的完整内容：
# Memento Tick Worker — System Prompt
You are a Memento Tick Worker: a short-lived, stateless, disciplined execution agent.
You have no memory of previous ticks. You start fresh every time.
## Your Lifecycle (execute in this exact order)
1. Read `docs/MASTER_PLAN.md`. Parse the Meta section for configuration.
2. Read `docs/HUMAN_NOTES.md`. Note any `[NOTE]` entries (ignore `[NOTE:READ]`).
3. Scan Phases in order. For each Phase:
- Check `depends`: all tasks in depended Phase must be `[x]` or `[-]`.
- Find the first task marked `[ ]` with `retries < max_retries`.
4. If no executable task found:
- If all tasks are `[x]`/`[-]`: write "🎉 ALL TASKS COMPLETE" to TICK_STATUS.md.
- If any `[!]` exists: write "⚠️ PIPELINE BLOCKED" to TICK_STATUS.md.
- Exit.
5. Mark the target task `[~]` in MASTER_PLAN.md.
6. Read `docs/PROJECT_MAP.md` for module context.
7. Load ONLY the files listed in the task's `context_files`.
8. If there are `[NOTE]` entries targeting this task ID or `global`, incorporate them.
9. Perform the work using surgical, targeted edits. NEVER output a full file.
10. Verify:
- Check: did you modify any file listed in `guard_files`? If yes → rollback → fail.
- Check: is your total diff > `max_diff_lines`? If yes → rollback → fail.
- Run the task's `verify` command. Capture exit code, stdout, stderr.
11. Write a TICK_STATUS.md entry (format below).
12. If verify exit code == 0:
- Mark task `[x]`. Run `git add -A && git commit -m "memento: complete {TASK_ID} {description}"`.
- If `tasks_completed_this_tick < max_tasks_per_tick`, go to step 3 for next task.
13. If verify exit code != 0:
- Rollback: `git checkout -- .`
- Increment `retries` in MASTER_PLAN.md.
- If `retries >= max_retries`: mark task `[!]`, add "⚠️ NEEDS ARCHITECT ATTENTION" to status.
- Clear `[~]` back to `[ ]` (or `[!]`).
14. Exit.
## TICK_STATUS.md Entry Format
## [{timestamp}] Tick #{tick_number}
- **Task**: {TASK_ID} [MODULE:{module}] {description}
- **Status**: ✅ SUCCESS | ❌ FAILED (retry {n}/{max}) | 🚫 BLOCKED
- **Verify Output**: {first 5 lines of stdout/stderr} (exit code {n})
- **Duration**: {time}
- **Error Analysis**: {your diagnosis of what went wrong — FAILED/BLOCKED only}
- **Files Modified**: {file (+lines -lines)} | (rolled back)
- **Diff Size**: {total lines changed}
- **Git Commit**: {hash} — "{message}" | (none — rollback)
- **Outputs**: {key interfaces/exports created — SUCCESS only, optional but encouraged}
## Iron Disciplines (violation = immediate failure)
1. **SURGICAL EDITS ONLY**: Never output a complete file. Use precise, targeted modifications.
2. **EVIDENCE-BASED**: Run `verify`. No exit code 0 = no `[x]`. No exceptions.
3. **NO SILENT GHOSTING**: If stuck, write full error + analysis to TICK_STATUS.md. Never exit silently.
4. **STAY IN YOUR LANE**: Only modify files in `context_files`. Never touch `guard_files`. Never edit task definitions in MASTER_PLAN.md (only checkbox state + retries). Never edit PROJECT_MAP.md.
5. **ATOMIC COMMITS**: `git commit` on success. `git checkout` on failure. Always.
## What You Are NOT
- You are NOT an architect. Do not redesign, re-plan, or question the task definition.
- You are NOT creative. Execute exactly what is specified.
- You are NOT persistent. After this tick, you will cease to exist.
9.2 Tick 入口脚本模板 (memento_tick.sh)
#!/usr/bin/env bash
set -euo pipefail
PROJECT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
PLAN="$PROJECT_DIR/docs/MASTER_PLAN.md"
STATUS="$PROJECT_DIR/docs/TICK_STATUS.md"
LOG_DIR="$PROJECT_DIR/logs"
TIMESTAMP=$(date +%Y-%m-%dT%H:%M:%S)
TICK_LOG="$LOG_DIR/tick_${TIMESTAMP}.log"
# 防撞车：确保同一时间只有一个 Tick Worker 运行
LOCK_FILE="$PROJECT_DIR/.memento.lock"
exec 200>"$LOCK_FILE"
if ! flock -n 200; then
echo "[$TIMESTAMP] Tick skipped: previous tick still running" >> "$STATUS"
exit 0
fi
# 检查 tick_mode
TICK_MODE=$(grep -oP 'tick_mode:\s*\K\w+' "$PLAN" || echo "stopped")
if [[ "$TICK_MODE" != "auto" ]]; then
echo "[$TIMESTAMP] Tick skipped: mode=$TICK_MODE" >> "$STATUS"
exit 0
fi
# 调用 LLM Agent 执行 Tick
SYSTEM_PROMPT="$(cat "$PROJECT_DIR/scripts/tick_worker_system_prompt.md")"
openclaw agent \
--system-prompt "$SYSTEM_PROMPT" \
--prompt "Read $PLAN, find the first executable task, complete it following the Memento Tick Worker protocol. Write results to $STATUS." \
--context-files "$PLAN" "$PROJECT_DIR/docs/PROJECT_MAP.md" "$PROJECT_DIR/docs/HUMAN_NOTES.md" \
2>&1 | tee "$TICK_LOG"
# 后处理：三阶段防爆清理
cd "$PROJECT_DIR"
if [[ -n $(git status --porcelain) ]]; then
echo "[$TIMESTAMP] WARNING: Dirty workspace detected. Running 3-phase cleanup." >> "$STATUS"
# Phase 1: 恢复已追踪文件
git checkout -- .
# Phase 2: 清理未追踪文件（排除保护列表）
if [[ -f ".memento_cleanignore" ]]; then
git clean -fd --exclude-from=.memento_cleanignore
else
git clean -fd
fi
# Phase 3: 兜底——如果还是脏的，紧急 stash
if [[ -n $(git status --porcelain) ]]; then
git stash --include-untracked -m "memento-emergency-stash-$TIMESTAMP"
echo "[$TIMESTAMP] CRITICAL: Emergency stash created. Manual inspection required." >> "$STATUS"
fi
fi
# 日志轮转
MAX_ENTRIES=$(grep -oP 'status_max_entries:\s*\K\d+' "$PLAN" || echo "50")
CURRENT_ENTRIES=$(grep -c '^\## \[' "$STATUS" || true)
if [[ $CURRENT_ENTRIES -gt $MAX_ENTRIES ]]; then
ARCHIVE_DIR="$PROJECT_DIR/logs/status_archive"
mkdir -p "$ARCHIVE_DIR"
mv "$STATUS" "$ARCHIVE_DIR/TICK_STATUS_$(date +%Y%m%d_%H%M%S).md"
echo "# TICK STATUS LOG" > "$STATUS"
echo "" >> "$STATUS"
echo "<!-- Rotated at $TIMESTAMP. Previous entries archived. -->" >> "$STATUS"
fi
# 告警检测
BLOCKED_COUNT=$(grep -c '\[!\]' "$PLAN" || true)
CIRCUIT_BROKEN=$(grep -c 'CIRCUIT BREAKER' "$STATUS" || true)
if [[ $BLOCKED_COUNT -gt 0 || $CIRCUIT_BROKEN -gt 0 ]]; then
cat > "$PROJECT_DIR/.memento_alert" << EOF_INNER
timestamp: $TIMESTAMP
blocked_tasks: $BLOCKED_COUNT
circuit_breaker: $([[ $CIRCUIT_BROKEN -gt 0 ]] && echo "TRIGGERED" || echo "OK")
message: Pipeline needs attention. $BLOCKED_COUNT task(s) blocked.
EOF_INNER
fi
# 如果一切正常且之前有告警，清除告警
if [[ $BLOCKED_COUNT -eq 0 && $CIRCUIT_BROKEN -eq 0 && -f "$PROJECT_DIR/.memento_alert" ]]; then
rm -f "$PROJECT_DIR/.memento_alert"
fi
9.3 Cron 配置
# 每 5 分钟执行一次
*/5 * * * * /path/to/project/scripts/memento_tick.sh >> /path/to/project/logs/cron.log 2>&1
十、完整工作流示例
人类："我想做一个带用户系统的 REST API"
│
▼
Architect（主 Session）：
├─ 与人类讨论确认：PostgreSQL + JWT + Express
├─ 写入 PROJECT_MAP.md（模块划分）
├─ 写入 MASTER_PLAN.md（15 个任务，3 个 Phase）
└─ "计划已就绪，运行 init 脚本后添加 crontab 即可启动"
│
▼
人类：添加 crontab，开始刷手机
│
▼
Tick #001 → T-101 数据库初始化 → ✅
Tick #001 → T-102 JWT 模块 → ✅ （同一 Tick 内连续完成 2 个快任务）
Tick #002 → T-103 密码哈希 → ✅
Tick #003 → T-201 连接中间件 → ❌ (retry 1/3)
Tick #004 → T-201 → ❌ (retry 2/3)
Tick #005 → T-201 → 🚫 BLOCKED
│
▼
人类打开 Dashboard，看到 T-201 阻塞
├─ 在 Notes 区写："别用 pg-pool 了，直接用 prisma"
└─ 继续刷手机
│
▼
Architect（读取 HUMAN_NOTES + TICK_STATUS）：
├─ 更新 PROJECT_MAP.md（MODULE:database 改为 Prisma）
├─ 修改 T-201 的 context_files 和 verify
├─ 新增 T-105 "安装并配置 Prisma"（插入 Phase 1）
├─ 重置 T-201 retries → 0，状态 [!] → [ ]
└─ 归档 HUMAN_NOTES 中的批注
│
▼
Tick #006 → T-105 安装 Prisma → ✅
Tick #007 → T-201 连接中间件（Prisma 版）→ ✅
Tick #008 → T-202 ... → ✅
│
... 持续推进 ...
│
▼
Tick #031 → 🎉 ALL TASKS COMPLETE
│
▼
人类打开 Dashboard："哦，做完了。" 移除 crontab。
Security & Transparency
Data Access — Exactly What Is Read
- Reads
<project-dir>/docs/MASTER_PLAN.mdto determine the current task - Reads
<project-dir>/docs/PROJECT_MAP.mdfor project structure awareness - Reads
<project-dir>/docs/HUMAN_NOTES.mdfor human annotations - Reads source code files listed in each task's
context_filesonly
Data Written
- Creates project scaffolding (
MASTER_PLAN.md,PROJECT_MAP.md,TICK_STATUS.md,HUMAN_NOTES.md,memento_tick.sh) - Updates checkbox states in
MASTER_PLAN.md(Tick Worker: only[ ]↔[x]/[!]/[~]) - Edits source files within the target project directory, limited to declared
context_files - Writes execution logs to
logs/tick_*.log - Creates git commits for successful task completions
Hard Safety Guards
- Diff size limit: Rejects changes > 200 lines per task (configurable)
- Guard files: Physically prevents modification of declared protected files
- Auto-rollback: Failed tasks are rolled back via
git checkout - Circuit breaker: Auto-pauses pipeline on sustained failures
Persistence & Autonomous Scheduling
- The
init_memento.shscript generates a bash script intended to be run viacron - The user must manually add this to their crontab to enable autonomous execution
- Stop at any time by removing the crontab entry or setting
tick_mode: stopped
Credentials
- Operates entirely locally
- Relies on
openclaw agentwith the system's existing LLM configurations - No new keys are requested or stored
Network Access
- No outbound network access by framework scripts
- Network access may occur only when user-defined
verifycommands require it (e.g.,npm install)
---
## 附录：文件结构总览
<project>/ ├── docs/ │ ├── MASTER_PLAN.md # 唯一真相源 │ ├── PROJECT_MAP.md # 项目认知地图 │ ├── TICK_STATUS.md # 执行状态流水账 │ └── HUMAN_NOTES.md # 人类批注通道 ├── logs/ │ ├── cron.log # cron 调度日志 │ ├── tick_2025-01-15T14:35:00.log │ └── tick_2025-01-15T14:40:00.log ├── scripts/ │ └── memento_tick.sh # Tick Worker 入口 ├── .memento_ignore # 上下文排除规则 └── src/ # 实际项目代码 └── ...