From ffec85f66d42dc8b100f7cdc3651fced829937d2 Mon Sep 17 00:00:00 2001 From: dtzp555 Date: Fri, 13 Mar 2026 05:11:07 +1000 Subject: [PATCH] docs: sync skill docs with lifecycle plugin plan --- README.md | 209 +++++++++++++++++++---------------- SKILL.md | 225 +++++++++++++++++++++++++------------- references/doctor-spec.md | 64 +++++++---- references/template.md | 10 +- 4 files changed, 321 insertions(+), 187 deletions(-) diff --git a/README.md b/README.md index 701f622..3541c88 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/SKILL.md b/SKILL.md index 25f0fab..57d0825 100644 --- a/SKILL.md +++ b/SKILL.md @@ -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 diff --git a/references/doctor-spec.md b/references/doctor-spec.md index ace8faf..eb8d7e1 100644 --- a/references/doctor-spec.md +++ b/references/doctor-spec.md @@ -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 -- 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.) +### 6. Archive consistency +- Are there files in `memory/session_archive/`? +- 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 diff --git a/references/template.md b/references/template.md index c5a7584..938bb01 100644 --- a/references/template.md +++ b/references/template.md @@ -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.