---
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
```
2. 在主对话中让 Architect 填写 `MASTER_PLAN.md` 和 `PROJECT_MAP.md`
3. 启动自动执行：
```bash
crontab -e
# 添加：*/5 * * * * /path/to/MyProject/scripts/memento_tick.sh
```
4. （可选）启动 Dashboard 看板监控：
```bash
bash scripts/dashboard.sh
```
5. 去刷手机。回来看 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 — 唯一真相源
T-101 [MODULE:database] Setup PostgreSQL schemacd src && npm test -- --grep "db-schema" && echo PASST-102 [MODULE:auth] Implement JWT token generationcd src && npm test -- --grep "jwt" && echo PASST-201 [MODULE:auth] Connect auth middleware to databasecd src && npm run test:integration && echo PASST-301 [MODULE:docs] Generate API documentationtest -f docs/api.md && echo PASS
**任务字段说明：**
| 字段 | 必须 | 说明 |
|------|------|------|
| `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` 精准加载。
Single-page game using Canvas API. No framework. Vanilla TypeScript.
DbConnection, UserRecord, SessionRecordAuthToken, AuthMiddlewaresrc/
├── 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
tests/ mirror src/ structure
**维护规则：**
- Architect 在创建/调整计划时同步更新
- Tick Worker **只读不写** PROJECT_MAP.md
- 如果 Worker 发现 MAP 与实际不符，在 TICK_STATUS.md 中报告，由 Architect 修正
### 3.3 TICK_STATUS.md — 执行状态流水账
PASS (exit code 0)a3f7b2c — "memento: complete T-101 database schema setup"PASS (exit code 0)b8e2d1f — "memento: complete T-102 JWT token generation"TypeError: pool.query is not a function (exit code 1)pool but middleware imports connection. Interface mismatch.
### 3.4 HUMAN_NOTES.md — 人类批注通道
> Dashboard 面板写入此文件。Tick Worker 每次启动时检查。Architect 也会读取。
改用 Redis 做 session 存储而不是 PostgreSQL。连接配置参考项目根目录的 redis.conf。
暂停 Phase 3 的所有任务，等 Phase 2 全部稳定再说。
JWT secret 从环境变量 JWT_SECRET 读取，别硬编码。
---
## 四、Tick 调度引擎规范
### 4.1 任务拾取算法
Tick Worker 醒来后执行以下逻辑：
FOR each Phase:
a. 检查 depends 条件
b. 在当前 Phase 内扫描任务：
c. 找到目标任务后，break
如果 tasks_completed_this_tick < max_tasks_per_tick 且剩余任务 estimate 合理：
回到步骤 3 继续拾取
否则退出
### 4.2 单任务执行流程
memento: complete {TASK_ID} {简述}）
### 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 创建计划
1. 与人类讨论项目需求，理解全貌
2. 设计模块划分，写入 `PROJECT_MAP.md`
3. 将需求分解为原子任务，写入 `MASTER_PLAN.md`
4. 每个任务必须有 `verify` 命令 —— **没有验证命令的任务不配存在**
5. 合理划分 Phase，声明 parallel 和 depends
### 8.2 监控与调整
1. 定期读取 `TICK_STATUS.md`（可由人类触发，或在对话中主动查看）
2. 对于 `[!]` 阻塞任务：
- 分析失败原因
- 修改任务定义（调整 verify、context_files、拆分子任务）
- 或修改 PROJECT_MAP（更新接口定义）
- 重置 retries 为 0，状态改回 `[ ]`
3. 对于 `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
该脚本执行：
1. 在项目目录下创建 `docs/` 目录
2. 生成 `MASTER_PLAN.md` 模板（含 Meta 区和示例 Phase）
3. 生成 `PROJECT_MAP.md` 模板
4. 生成 `TICK_STATUS.md`（空）
5. 生成 `HUMAN_NOTES.md`（空）
6. 创建 `logs/` 目录
7. 生成 `scripts/memento_tick.sh` —— Tick Worker 的入口脚本
8. 生成 `.memento_ignore`（排除 `node_modules/`, `.git/`, `logs/` 等）
9. 生成 `scripts/tick_worker_system_prompt.md` —— 注入给 Worker 的全套纪律法则和 Output 规范。
10. 生成 `.memento_cleanignore`（保护 `node_modules/`, `.env`, `vendor/` 等）
11. 输出提示：“请将以下行添加到 crontab 以启动自动执行”
### 9.1.1 Tick Worker System Prompt 模板 (tick_worker_system_prompt.md)
以下是 `init_memento.sh` 应生成的 `scripts/tick_worker_system_prompt.md` 的完整内容：
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.
docs/MASTER_PLAN.md. Parse the Meta section for configuration.docs/HUMAN_NOTES.md. Note any [NOTE] entries (ignore [NOTE:READ]).depends: all tasks in depended Phase must be [x] or [-].[ ] with retries < max_retries.[x]/[-]: write "🎉 ALL TASKS COMPLETE" to TICK_STATUS.md.[!] exists: write "⚠️ PIPELINE BLOCKED" to TICK_STATUS.md.[~] in MASTER_PLAN.md.docs/PROJECT_MAP.md for module context.context_files.[NOTE] entries targeting this task ID or global, incorporate them.guard_files? If yes → rollback → fail.max_diff_lines? If yes → rollback → fail.verify command. Capture exit code, stdout, stderr.[x]. Run git add -A && git commit -m "memento: complete {TASK_ID} {description}".tasks_completed_this_tick < max_tasks_per_tick, go to step 3 for next task.git checkout -- .retries in MASTER_PLAN.md.retries >= max_retries: mark task [!], add "⚠️ NEEDS ARCHITECT ATTENTION" to status.[~] back to [ ] (or [!]).verify. No exit code 0 = no [x]. No exceptions.context_files. Never touch guard_files. Never edit task definitions in MASTER_PLAN.md (only checkbox state + retries). Never edit PROJECT_MAP.md.git commit on success. git checkout on failure. Always.
### 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"
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=$(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
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 "" >> "$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 * /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.md` to determine the current task
- Reads `<project-dir>/docs/PROJECT_MAP.md` for project structure awareness
- Reads `<project-dir>/docs/HUMAN_NOTES.md` for human annotations
- Reads source code files listed in each task's `context_files` only
### 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.sh` script generates a bash script intended to be run via `cron`
- 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 agent` with 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 `verify` commands 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/ # 实际项目代码
└── ...
共 1 个版本