mirror of
https://github.com/dtzp555-max/memory-continuity.git
synced 2026-07-21 21:15:07 +00:00
docs: sync skill docs with lifecycle plugin plan
This commit is contained in:
@@ -1,44 +1,65 @@
|
||||
# memory-continuity
|
||||
|
||||
OpenClaw skill for **short-term working continuity** — so your agent can pick up
|
||||
exactly where it left off after a gateway crash, `/new`, model fallback, or
|
||||
context compaction.
|
||||
OpenClaw skill for **short-term working continuity** — so an agent can recover
|
||||
structured in-flight work state after `/new`, reset, gateway interruption,
|
||||
model fallback, or compaction.
|
||||
|
||||
## What problem does this solve?
|
||||
|
||||
When your gateway dies mid-conversation, or you hit `/new` to start fresh, or
|
||||
the model falls back to a different provider — your agent loses its working
|
||||
context. Long-term memory can tell it *what it knows*, but not *what it was
|
||||
doing*. This skill fills that gap.
|
||||
OpenClaw already preserves a lot:
|
||||
- transcripts
|
||||
- compaction summaries
|
||||
- memory files
|
||||
- session memory search
|
||||
|
||||
**One-line summary:** Long-term memory = what you know. This skill = what you
|
||||
are doing right now.
|
||||
But those do not always answer the most operational question:
|
||||
|
||||
> What were we doing right now, where did we stop, and what should happen next?
|
||||
|
||||
That is the problem this skill solves.
|
||||
|
||||
**One-line summary:**
|
||||
- long-term memory = what you know
|
||||
- memory continuity = what you are doing right now
|
||||
|
||||
## Current architecture stance
|
||||
|
||||
This repository now treats the skill as:
|
||||
- a **behavior contract**
|
||||
- a **fallback implementation**
|
||||
- a **human-readable protocol** for structured working-state checkpoints
|
||||
|
||||
The planned primary runtime path is a **standard lifecycle plugin** that can
|
||||
improve startup, `/new`, and compaction continuity **without consuming
|
||||
OpenClaw’s exclusive `contextEngine` slot**.
|
||||
|
||||
A ContextEngine implementation remains a **future option**, not the default
|
||||
v1 direction.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Install
|
||||
|
||||
```bash
|
||||
# Go to your OpenClaw workspace skills directory
|
||||
cd ~/.openclaw/workspace/skills/
|
||||
|
||||
# Clone
|
||||
git clone https://github.com/dtzp555-max/memory-continuity.git
|
||||
|
||||
# That's it. No npm install, no API keys, no database.
|
||||
```
|
||||
|
||||
### Test it
|
||||
No npm install, no API keys, no external database.
|
||||
|
||||
1. Start a conversation with your agent about a multi-step task
|
||||
2. Chat for a few turns, make some decisions
|
||||
3. Check: does `memory/CURRENT_STATE.md` exist in your workspace? Does it
|
||||
reflect what you were doing?
|
||||
4. Type `/new` to start a fresh session
|
||||
5. The agent should read `CURRENT_STATE.md` and ask:
|
||||
*"Last session we were working on X. Want to continue?"*
|
||||
### Test the current skill version
|
||||
|
||||
If step 5 works, the skill is doing its job.
|
||||
1. Start a multi-step task with your agent
|
||||
2. Make a few concrete decisions
|
||||
3. Check whether `memory/CURRENT_STATE.md` exists and reflects the work state
|
||||
4. Trigger `/new`
|
||||
5. Ask a recovery question like:
|
||||
- “刚才我们说到哪了”
|
||||
- “continue”
|
||||
- “what were we doing”
|
||||
|
||||
A good recovery should surface the current objective / step / next action,
|
||||
not generic small talk.
|
||||
|
||||
### Run the doctor
|
||||
|
||||
@@ -46,32 +67,17 @@ If step 5 works, the skill is doing its job.
|
||||
python3 scripts/continuity_doctor.py --workspace ~/.openclaw/workspace
|
||||
```
|
||||
|
||||
Sample output:
|
||||
```
|
||||
Continuity Doctor — scanning: /Users/you/.openclaw/workspace
|
||||
============================================================
|
||||
## How the current skill version works
|
||||
|
||||
[OK] memory/CURRENT_STATE.md exists
|
||||
[OK] CURRENT_STATE.md is fresh (0.3h old)
|
||||
[OK] Template compliance: all sections present
|
||||
[WARNING] Unsurfaced Results section is not empty — review needed
|
||||
[INFO] Found 3 session archive(s), latest: 2026-03-12_14-30.md
|
||||
The skill defines a discipline around one file:
|
||||
- `memory/CURRENT_STATE.md`
|
||||
|
||||
Overall status: WARNING
|
||||
```
|
||||
That file is the short-term workbench for active work. It is:
|
||||
- overwritten, not appended
|
||||
- intentionally short
|
||||
- structured for fast recovery
|
||||
|
||||
## How it works
|
||||
|
||||
The skill installs a behavioral protocol via `SKILL.md`. When loaded, the agent
|
||||
follows these rules:
|
||||
|
||||
1. **Session start:** Read `memory/CURRENT_STATE.md`, brief the user, wait for
|
||||
confirmation
|
||||
2. **During work:** Overwrite the state file at key moments (decisions,
|
||||
completed steps, errors, before long tool calls, every ~10 turns)
|
||||
3. **Session end / `/new`:** Final state save + archive a timestamped snapshot
|
||||
|
||||
The state file uses a fixed template:
|
||||
### The checkpoint shape
|
||||
|
||||
```markdown
|
||||
# Current State
|
||||
@@ -97,75 +103,92 @@ None
|
||||
None
|
||||
```
|
||||
|
||||
The entire file is designed to be read in 15 seconds. It is overwritten (not
|
||||
appended) on every update, keeping it permanently short.
|
||||
## Recovery rules
|
||||
|
||||
## Architecture position
|
||||
In recovery scenarios, the skill expects the agent to prioritize:
|
||||
- Objective
|
||||
- Current Step
|
||||
- Next Action
|
||||
- Blockers
|
||||
- Unsurfaced Results
|
||||
|
||||
This skill occupies a specific niche. Here is how it relates to other tools:
|
||||
A generic greeting should **not** outrank recovery state when the checkpoint
|
||||
contains active work.
|
||||
|
||||
| Layer | Tool | What it stores |
|
||||
|---|---|---|
|
||||
| Working state | **memory-continuity** (this skill) | What you are doing *right now* |
|
||||
| Stable facts | OpenClaw native markdown memory | Preferences, decisions, knowledge |
|
||||
| Retrieval | memory-lancedb-pro / similar | Searchable long-term history |
|
||||
## Relationship to native OpenClaw features
|
||||
|
||||
These layers are complementary. This skill has **zero dependency** on any
|
||||
database or external memory plugin. It works with plain markdown files that
|
||||
live in your workspace and can be backed up with `git` or `cp`.
|
||||
### Native OpenClaw already handles
|
||||
- transcript persistence
|
||||
- compaction
|
||||
- pre-compaction `memoryFlush`
|
||||
- session memory search
|
||||
- system prompt/bootstrap assembly
|
||||
|
||||
## File structure
|
||||
### memory-continuity adds
|
||||
- a **structured working-state checkpoint**
|
||||
- explicit short-term recovery fields
|
||||
- a deterministic place to look for active work state
|
||||
- explicit handling for `Unsurfaced Results`
|
||||
|
||||
```
|
||||
### Important boundary
|
||||
Session memory search is useful for:
|
||||
- “what did we discuss before?”
|
||||
- “what decision was mentioned in a prior session?”
|
||||
|
||||
Memory continuity is for:
|
||||
- “what are we doing right now?”
|
||||
- “where did we stop?”
|
||||
- “what should happen next?”
|
||||
|
||||
## Repository layout
|
||||
|
||||
```text
|
||||
memory-continuity/
|
||||
├── SKILL.md # Core skill (loaded by OpenClaw)
|
||||
├── README.md # This file
|
||||
├── LICENSE # MIT
|
||||
├── SKILL.md
|
||||
├── README.md
|
||||
├── LICENSE
|
||||
├── references/
|
||||
│ ├── template.md # CURRENT_STATE.md blank template
|
||||
│ └── doctor-spec.md # Doctor check specifications
|
||||
│ ├── template.md
|
||||
│ └── doctor-spec.md
|
||||
└── scripts/
|
||||
└── continuity_doctor.py # Diagnostic tool (reports only, no auto-repair)
|
||||
└── continuity_doctor.py
|
||||
```
|
||||
|
||||
At runtime, the skill creates these files in your workspace:
|
||||
At runtime, the skill works primarily with:
|
||||
|
||||
```
|
||||
```text
|
||||
$WORKSPACE/
|
||||
└── memory/
|
||||
├── CURRENT_STATE.md # Live workbench (overwritten each update)
|
||||
└── session_archive/ # Timestamped snapshots from past sessions
|
||||
├── 2026-03-12_14-30.md
|
||||
└── ...
|
||||
├── CURRENT_STATE.md
|
||||
└── session_archive/
|
||||
```
|
||||
|
||||
## Design principles
|
||||
|
||||
1. **Zero dependencies.** No database, no API, no npm packages. Just files.
|
||||
2. **Backup = copy.** The entire state is in `memory/`. Back it up however you
|
||||
back up your workspace.
|
||||
3. **Overwrite, don't append.** CURRENT_STATE.md is a workbench, not a journal.
|
||||
It stays short because it is replaced on every update.
|
||||
4. **Diagnose, don't auto-repair.** The doctor script flags problems for you to
|
||||
fix. Automated repair of state files is too risky at this stage.
|
||||
5. **Complement, don't compete.** This skill does not replace long-term memory.
|
||||
It solves a different problem (crash recovery vs knowledge retrieval).
|
||||
1. **Files are the source of truth**
|
||||
2. **Structured checkpoint beats free-form recollection**
|
||||
3. **Recovery must prefer truth over confident guessing**
|
||||
4. **This complements native OpenClaw memory; it does not replace it**
|
||||
5. **Read access is helpful, but should not be the only long-term path**
|
||||
6. **The primary plugin direction should coexist with other ecosystem plugins such as `lossless-claw`**
|
||||
|
||||
## Current status
|
||||
## Current roadmap
|
||||
|
||||
**v0.2 — Draft / early version**
|
||||
### Phase 1
|
||||
Strengthen the current skill version:
|
||||
- tighten recovery behavior
|
||||
- tighten checkpoint discipline
|
||||
- improve doctor and docs
|
||||
|
||||
What works:
|
||||
- SKILL.md protocol with discipline rules
|
||||
- CURRENT_STATE.md template
|
||||
- Continuity doctor diagnostic script
|
||||
- Session archive on `/new`
|
||||
### Phase 2
|
||||
Build a **standard lifecycle plugin** as the primary runtime path:
|
||||
- startup recovery behavior
|
||||
- `/new` checkpointing
|
||||
- compaction-boundary checkpointing
|
||||
- end-of-run safety writes
|
||||
|
||||
Planned:
|
||||
- Plugin version with `command:new` and `before_agent_start` hooks
|
||||
(for guaranteed save/restore without relying on agent self-discipline)
|
||||
- More real-world validation across different gateway configurations
|
||||
- Sub-agent continuity handover protocol
|
||||
### Future option
|
||||
Evaluate a ContextEngine variant later only if the slot tradeoff is justified.
|
||||
|
||||
## License
|
||||
|
||||
|
||||
@@ -1,37 +1,77 @@
|
||||
---
|
||||
name: memory-continuity
|
||||
description: >
|
||||
Short-term working continuity for OpenClaw agents. Preserves in-flight state
|
||||
across gateway restarts, /new, model fallback, and context compaction.
|
||||
Use this skill whenever an agent needs to survive session breaks without
|
||||
losing what it was doing. Triggers on: session start, /new, context recovery,
|
||||
"where were we", "continue", resuming work, or any situation where recent
|
||||
working state may have been lost. This is NOT a long-term memory system —
|
||||
it is a crash-recovery workbench.
|
||||
Short-term working continuity for OpenClaw agents. Preserves structured
|
||||
in-flight work state across gateway restarts, /new, reset, model fallback,
|
||||
and context compaction. This skill is the human-readable protocol and
|
||||
fallback layer for working-state recovery; it complements native OpenClaw
|
||||
memory, compaction, and session memory search rather than replacing them.
|
||||
Use when an agent needs to survive session breaks without losing what it was
|
||||
doing.
|
||||
---
|
||||
|
||||
# memory-continuity
|
||||
|
||||
Lightweight continuity layer that keeps a single overwrite-oriented state file
|
||||
(`memory/CURRENT_STATE.md`) so any agent can pick up exactly where it left off
|
||||
after a restart, `/new`, gateway crash, model fallback, or context compaction.
|
||||
Lightweight continuity layer built around a single overwrite-oriented state file
|
||||
(`memory/CURRENT_STATE.md`). Its job is simple: keep a compact, structured
|
||||
checkpoint of **what the agent is doing right now** so work can resume after
|
||||
`/new`, reset, gateway interruption, compaction, or handoff.
|
||||
|
||||
## Positioning
|
||||
|
||||
This skill is **not** the whole long-term architecture.
|
||||
|
||||
It is the current:
|
||||
- **behavior contract** for agents
|
||||
- **fallback implementation** when no plugin is installed
|
||||
- **human-readable protocol** for maintaining working-state continuity
|
||||
|
||||
Longer term, the primary runtime path is expected to be a **standard lifecycle
|
||||
plugin** that improves save/restore reliability without consuming OpenClaw’s
|
||||
exclusive `contextEngine` slot.
|
||||
|
||||
## Why this exists
|
||||
|
||||
Long-term memory (vector DB, markdown journals) stores *what you know*.
|
||||
This skill stores *what you are doing right now*. They solve different problems.
|
||||
OpenClaw already has native systems for:
|
||||
- transcript persistence
|
||||
- compaction summaries
|
||||
- pre-compaction `memoryFlush`
|
||||
- session-aware `memory_search`
|
||||
|
||||
When a gateway crashes mid-task, no amount of long-term memory recall can tell
|
||||
the next session: "you were halfway through step 3, the user approved option B,
|
||||
and the blocker was X." That is what CURRENT_STATE.md does.
|
||||
Those are valuable, but they answer a different question.
|
||||
|
||||
They help with:
|
||||
- what was discussed before?
|
||||
- what knowledge or facts were written down?
|
||||
|
||||
This skill helps with:
|
||||
- what are we doing **right now**?
|
||||
- where did we stop?
|
||||
- what should happen next?
|
||||
- what result exists but has not yet been surfaced?
|
||||
|
||||
That is why `CURRENT_STATE.md` exists.
|
||||
|
||||
## Source of truth
|
||||
|
||||
The source of truth for working-state continuity is:
|
||||
- `memory/CURRENT_STATE.md`
|
||||
|
||||
This file should stay:
|
||||
- short
|
||||
- structured
|
||||
- overwrite-oriented
|
||||
- readable by both humans and agents
|
||||
|
||||
It is a **checkpoint**, not a journal.
|
||||
|
||||
## File layout
|
||||
|
||||
```
|
||||
```text
|
||||
$WORKSPACE/
|
||||
├── memory/
|
||||
│ ├── CURRENT_STATE.md # THE workbench (overwritten, never appended)
|
||||
│ └── session_archive/ # compressed snapshots from past sessions
|
||||
│ ├── CURRENT_STATE.md # live workbench (overwrite, never append-log)
|
||||
│ └── session_archive/ # optional frozen snapshots
|
||||
│ ├── 2026-03-12_14-30.md
|
||||
│ └── ...
|
||||
```
|
||||
@@ -40,53 +80,88 @@ $WORKSPACE/
|
||||
|
||||
## MANDATORY PROTOCOL
|
||||
|
||||
### 1. On every session start
|
||||
### 1. On session start or recovery-like prompts
|
||||
|
||||
```
|
||||
IF memory/CURRENT_STATE.md exists:
|
||||
READ it
|
||||
Tell user: "Last session we were working on [Objective]. We reached [Current Step]. Want to continue?"
|
||||
WAIT for user confirmation before proceeding
|
||||
ELSE:
|
||||
Create memory/CURRENT_STATE.md with empty template (see below)
|
||||
```
|
||||
If `memory/CURRENT_STATE.md` exists:
|
||||
1. read it
|
||||
2. determine whether it contains meaningful active work
|
||||
3. if active work exists and the user is asking to continue / recover / resume,
|
||||
**surface the recovered state before generic greeting or chit-chat**
|
||||
4. prefer truth over guessing
|
||||
|
||||
### 2. When to update CURRENT_STATE.md (the discipline rules)
|
||||
If no active work exists:
|
||||
- normal conversation flow is fine
|
||||
|
||||
Update the file by **overwriting** it (not appending) at these moments:
|
||||
If the file does not exist:
|
||||
- create it from the template below when work begins
|
||||
|
||||
### 2. Recovery priority rule
|
||||
|
||||
In recovery scenarios such as:
|
||||
- `/new`
|
||||
- reset
|
||||
- “刚才我们说到哪了”
|
||||
- “continue”
|
||||
- “resume”
|
||||
- “what were we doing”
|
||||
- obvious post-interruption continuation
|
||||
|
||||
Do **not** open with generic greetings if `CURRENT_STATE.md` contains active
|
||||
work. First surface:
|
||||
- Objective
|
||||
- Current Step
|
||||
- Next Action
|
||||
- Blockers (if any)
|
||||
- Unsurfaced Results (if any)
|
||||
|
||||
Failure to do this is a continuity failure, not a style preference.
|
||||
|
||||
### 3. When to update CURRENT_STATE.md
|
||||
|
||||
Update the file by **overwriting** it, not appending, at these moments:
|
||||
|
||||
| Trigger | Why |
|
||||
|---|---|
|
||||
| User confirms a decision | Decisions are the hardest thing to reconstruct |
|
||||
| A task step completes | Marks progress so next session knows where to start |
|
||||
| An error or blocker appears | Prevents the next session from hitting the same wall |
|
||||
| Before any tool call that might take long | If gateway dies during the call, state is already saved |
|
||||
| User says "let's stop here" or similar | Explicit save point |
|
||||
| Every ~10 turns of substantive conversation | Periodic checkpoint against silent context loss |
|
||||
| User confirms a decision | Decisions are hard to reconstruct later |
|
||||
| A concrete task step completes | Marks true progress for recovery |
|
||||
| A blocker or error appears | Prevents repeated failure after reset |
|
||||
| Before long-running or risky tool work | Preserves a recovery point before interruption |
|
||||
| Before `/new` / reset-like boundary | Prevents deliberate context reset from dropping work state |
|
||||
| Before handoff / subagent exit | Preserves outputs and unsurfaced results |
|
||||
| After a substantive state change | Keeps checkpoint aligned with actual work |
|
||||
|
||||
**The update must be quick.** Write only what changed. The entire file should
|
||||
stay under 40 lines. If you find yourself writing more, you are journaling,
|
||||
not checkpointing. Stop and compress.
|
||||
### 4. Keep the checkpoint small
|
||||
|
||||
### 3. On `/new` or session end
|
||||
`CURRENT_STATE.md` should usually stay under about 40 lines and be readable in
|
||||
15 seconds.
|
||||
|
||||
Before the session closes:
|
||||
If it grows too long, compress it.
|
||||
If it turns into a diary, you are using the wrong file.
|
||||
|
||||
1. Do a final overwrite of `memory/CURRENT_STATE.md` with latest state
|
||||
2. Copy a timestamped snapshot to `memory/session_archive/YYYY-MM-DD_HH-MM.md`
|
||||
3. The snapshot is a frozen record; CURRENT_STATE.md is the live workbench
|
||||
|
||||
If gateway crashes before you can do this, that is OK — the last mid-session
|
||||
checkpoint in CURRENT_STATE.md is your recovery point. It will not be perfect,
|
||||
but it will be vastly better than starting from zero.
|
||||
|
||||
### 4. Result surfacing rule
|
||||
### 5. Result surfacing rule
|
||||
|
||||
If you are a sub-agent or execution agent:
|
||||
- Before exiting, write your key results into CURRENT_STATE.md under `## Unsurfaced Results`
|
||||
- The main agent MUST check this section on startup and relay findings to the user
|
||||
- write unreported outcomes into `## Unsurfaced Results`
|
||||
- do not assume the main agent has already forwarded them
|
||||
|
||||
This prevents the #1 silent failure: sub-agent did the work, but nobody saw it.
|
||||
This prevents a common failure mode:
|
||||
- work finished
|
||||
- result existed
|
||||
- nobody surfaced it to the user
|
||||
|
||||
### 6. Relationship to native OpenClaw memory
|
||||
|
||||
Do not use this skill to replace:
|
||||
- `MEMORY.md`
|
||||
- `memory/YYYY-MM-DD.md`
|
||||
- compaction summaries
|
||||
- session memory search
|
||||
|
||||
Use it only for **active working state**.
|
||||
|
||||
A good rule of thumb:
|
||||
- if the content matters because it is true long-term → put it in long-term memory
|
||||
- if the content matters because it tells the next session what to do next → put it here
|
||||
|
||||
---
|
||||
|
||||
@@ -115,13 +190,12 @@ This prevents the #1 silent failure: sub-agent did the work, but nobody saw it.
|
||||
[Results from sub-agents or tools not yet shown to user, or "None"]
|
||||
```
|
||||
|
||||
**Rules for this template:**
|
||||
- Every field is mandatory. Write "None" rather than omitting a section.
|
||||
- `Objective` and `Next Action` are the two most critical fields. If you can
|
||||
only save two things before a crash, save these.
|
||||
- `Key Decisions` caps at 3 items. Older decisions belong in long-term memory,
|
||||
not here.
|
||||
- The entire file should be readable in 15 seconds. If it takes longer, trim it.
|
||||
### Template rules
|
||||
- Every field is mandatory. Use `None` rather than omission.
|
||||
- `Objective` and `Next Action` are the two most critical fields.
|
||||
- `Key Decisions` should stay short; move older material to long-term memory.
|
||||
- `Unsurfaced Results` should be explicit, not implied.
|
||||
- If `Objective` is empty / placeholder / idle, recovery should not pretend there is active work.
|
||||
|
||||
---
|
||||
|
||||
@@ -133,27 +207,30 @@ Run `scripts/continuity_doctor.py` to check workspace health:
|
||||
python3 scripts/continuity_doctor.py --workspace /path/to/workspace
|
||||
```
|
||||
|
||||
It checks:
|
||||
- Does `memory/CURRENT_STATE.md` exist?
|
||||
- Is it stale (not updated in the last session)?
|
||||
- Does `Objective` match any active tasks file?
|
||||
- Are there `Unsurfaced Results` that were never addressed?
|
||||
- Are there session archives without a corresponding state update?
|
||||
The doctor reports only. It does **not** auto-repair.
|
||||
|
||||
The doctor **reports only** — it does not auto-repair. You decide what to fix.
|
||||
It should help answer:
|
||||
- does `CURRENT_STATE.md` exist?
|
||||
- is it stale?
|
||||
- does it follow the template?
|
||||
- are `Unsurfaced Results` still present?
|
||||
- does recovery state look usable?
|
||||
|
||||
---
|
||||
|
||||
## What this skill is NOT
|
||||
|
||||
- Not a long-term memory system (use OpenClaw's native markdown memory or LanceDB for that)
|
||||
- Not a conversation log or journal (CURRENT_STATE.md is overwritten, not appended)
|
||||
- Not a task manager (use OpenSpec or tasks.md for project planning)
|
||||
- Not dependent on any external database (works with plain files only)
|
||||
- Not a long-term memory system
|
||||
- Not a replacement for OpenClaw compaction
|
||||
- Not a replacement for `memoryFlush`
|
||||
- Not a replacement for session transcript memory search
|
||||
- Not a task manager or project database
|
||||
- Not a conversation log or journal
|
||||
- Not dependent on any external database
|
||||
|
||||
## Compatibility
|
||||
|
||||
- Works with any OpenClaw agent (main or sub-agent)
|
||||
- No external dependencies (no npm install, no API keys, no database)
|
||||
- Backup: `git add memory/` or `cp -r memory/ /backup/` — that is the entire disaster recovery plan
|
||||
- Can coexist with memory-lancedb-pro, hippocampus, or any other memory skill
|
||||
- Works as a plain-skill fallback today
|
||||
- Compatible with main agents and subagents when they can maintain the file
|
||||
- Designed to evolve toward a **standard lifecycle plugin** as the primary runtime path
|
||||
- Intentionally avoids depending on the exclusive `contextEngine` slot as the default architecture
|
||||
|
||||
+44
-18
@@ -9,50 +9,74 @@ It reports problems but does **not** auto-fix them.
|
||||
## Design philosophy
|
||||
|
||||
- **Diagnose, don't repair.** Automated repair of state files is dangerous
|
||||
because incorrect "fixes" can overwrite valid state. The doctor flags
|
||||
issues for human or agent review.
|
||||
because incorrect fixes can overwrite valid state.
|
||||
- **Fast and offline.** No API calls, no database queries. Reads files only.
|
||||
- **Exit codes matter.** 0 = healthy, 1 = warnings found, 2 = critical issues.
|
||||
- **Working-state focus.** The doctor validates active-work recovery hygiene,
|
||||
not long-term memory quality.
|
||||
|
||||
## Checks performed
|
||||
|
||||
### 1. Existence check
|
||||
- Does `memory/CURRENT_STATE.md` exist?
|
||||
- Severity: CRITICAL if missing (no recovery possible)
|
||||
- Severity: CRITICAL if missing (no deterministic recovery point)
|
||||
|
||||
### 2. Staleness check
|
||||
- When was `CURRENT_STATE.md` last modified?
|
||||
- If older than the most recent session transcript, it is stale.
|
||||
- If older than the most recent relevant session activity, it is stale.
|
||||
- Severity: WARNING
|
||||
|
||||
### 3. Template compliance
|
||||
- Does the file contain all mandatory sections?
|
||||
(Objective, Current Step, Key Decisions, Next Action, Blockers, Unsurfaced Results)
|
||||
- Are any sections still showing placeholder text like `[One sentence: ...]`?
|
||||
- Severity: WARNING for missing sections, INFO for placeholder text
|
||||
(`Objective`, `Current Step`, `Key Decisions`, `Next Action`, `Blockers`, `Unsurfaced Results`)
|
||||
- Are any sections still showing placeholder text?
|
||||
- Severity: WARNING for missing sections, INFO/WARNING for unresolved placeholders depending on severity
|
||||
|
||||
### 4. Unsurfaced results
|
||||
### 4. Active-work usability
|
||||
- Does `Objective` appear meaningful, or is it empty / placeholder / idle?
|
||||
- If active work exists, does `Next Action` look usable?
|
||||
- Severity: WARNING when a checkpoint exists but does not provide a usable recovery surface
|
||||
|
||||
### 5. Unsurfaced results
|
||||
- Is the `Unsurfaced Results` section non-empty?
|
||||
- If yes, someone needs to review those results.
|
||||
- If yes, someone likely still needs to review or forward those results.
|
||||
- Severity: WARNING
|
||||
|
||||
### 5. Archive consistency
|
||||
### 6. Archive consistency
|
||||
- Are there files in `memory/session_archive/`?
|
||||
- Does the newest archive have a different Objective than CURRENT_STATE.md?
|
||||
(This is expected if the user switched tasks, but worth flagging.)
|
||||
- Does the newest archive differ significantly from `CURRENT_STATE.md`?
|
||||
(This may be expected after task switches, but is worth flagging.)
|
||||
- Severity: INFO
|
||||
|
||||
### 6. Conflict detection (optional, if tasks file exists)
|
||||
- If a `tasks.md` or `openspec/` directory exists, does the Objective in
|
||||
CURRENT_STATE.md align with any active task?
|
||||
- Severity: INFO (alignment is nice-to-have, not mandatory)
|
||||
### 7. Recovery-priority hygiene (best-effort)
|
||||
- If workspace/session evidence suggests a recovery scenario recently occurred,
|
||||
did the agent still prefer generic greeting over recovered work state?
|
||||
- Severity: WARNING when detectable
|
||||
- Note: this may depend on transcript/session inspection and can remain best-effort
|
||||
|
||||
### 8. Optional alignment checks
|
||||
- If a `tasks.md`, `openspec/`, or similar planning artifact exists, does the
|
||||
`Objective` roughly align with active work?
|
||||
- Severity: INFO
|
||||
|
||||
## Important boundaries
|
||||
The doctor is **not** trying to replace:
|
||||
- OpenClaw compaction summaries
|
||||
- native `memoryFlush`
|
||||
- session transcript memory search
|
||||
|
||||
It only answers:
|
||||
- is the working-state checkpoint present?
|
||||
- is it fresh?
|
||||
- is it structurally usable for recovery?
|
||||
|
||||
## Output format
|
||||
|
||||
```
|
||||
```text
|
||||
[CRITICAL] memory/CURRENT_STATE.md does not exist
|
||||
[WARNING] CURRENT_STATE.md is stale (last modified 2h ago, session ran 30m ago)
|
||||
[WARNING] Unsurfaced Results section is not empty — review needed
|
||||
[WARNING] Recovery state exists but Next Action is placeholder text
|
||||
[INFO] Archive objective differs from current objective (task switch?)
|
||||
[OK] Template compliance: all sections present
|
||||
```
|
||||
@@ -61,4 +85,6 @@ It reports problems but does **not** auto-fix them.
|
||||
|
||||
- Multi-workspace scan (check all sub-agent workspaces)
|
||||
- JSON output mode for programmatic consumption
|
||||
- Integration with OpenClaw cron for scheduled health checks
|
||||
- Integration with scheduled health checks
|
||||
- More transcript-aware recovery-priority detection
|
||||
- Validation support for future lifecycle-plugin checkpoints
|
||||
|
||||
@@ -8,7 +8,7 @@
|
||||
[What step are we on, what was the last thing completed]
|
||||
|
||||
## Key Decisions
|
||||
- None yet
|
||||
- None
|
||||
|
||||
## Next Action
|
||||
[Exactly what should happen next]
|
||||
@@ -18,3 +18,11 @@ None
|
||||
|
||||
## Unsurfaced Results
|
||||
None
|
||||
|
||||
---
|
||||
|
||||
## Template notes
|
||||
- Use this file for **active working state**, not long-term memory.
|
||||
- Overwrite it; do not turn it into a running journal.
|
||||
- If `Objective` is empty, placeholder, or idle, recovery should not pretend active work exists.
|
||||
- In recovery scenarios, agents should surface this state before generic greetings when active work is present.
|
||||
|
||||
Reference in New Issue
Block a user