diff --git a/skills/memory-continuity/README.md b/skills/memory-continuity/README.md new file mode 100644 index 0000000..3541c88 --- /dev/null +++ b/skills/memory-continuity/README.md @@ -0,0 +1,195 @@ +# memory-continuity + +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? + +OpenClaw already preserves a lot: +- transcripts +- compaction summaries +- memory files +- session memory search + +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 +cd ~/.openclaw/workspace/skills/ +git clone https://github.com/dtzp555-max/memory-continuity.git +``` + +No npm install, no API keys, no external database. + +### Test the current skill version + +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 + +```bash +python3 scripts/continuity_doctor.py --workspace ~/.openclaw/workspace +``` + +## How the current skill version works + +The skill defines a discipline around one file: +- `memory/CURRENT_STATE.md` + +That file is the short-term workbench for active work. It is: +- overwritten, not appended +- intentionally short +- structured for fast recovery + +### The checkpoint shape + +```markdown +# Current State +> Last updated: 2026-03-12T14:30:00Z + +## Objective +Build the user authentication module + +## Current Step +Completed JWT token generation, starting refresh endpoint + +## Key Decisions +- Using RS256 for token signing (user approved) +- Token expiry: 15 minutes access, 7 days refresh + +## Next Action +Implement POST /auth/refresh endpoint + +## Blockers +None + +## Unsurfaced Results +None +``` + +## Recovery rules + +In recovery scenarios, the skill expects the agent to prioritize: +- Objective +- Current Step +- Next Action +- Blockers +- Unsurfaced Results + +A generic greeting should **not** outrank recovery state when the checkpoint +contains active work. + +## Relationship to native OpenClaw features + +### Native OpenClaw already handles +- transcript persistence +- compaction +- pre-compaction `memoryFlush` +- session memory search +- system prompt/bootstrap assembly + +### 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 +├── README.md +├── LICENSE +├── references/ +│ ├── template.md +│ └── doctor-spec.md +└── scripts/ + └── continuity_doctor.py +``` + +At runtime, the skill works primarily with: + +```text +$WORKSPACE/ +└── memory/ + ├── CURRENT_STATE.md + └── session_archive/ +``` + +## Design principles + +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 roadmap + +### Phase 1 +Strengthen the current skill version: +- tighten recovery behavior +- tighten checkpoint discipline +- improve doctor and docs + +### 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 + +### Future option +Evaluate a ContextEngine variant later only if the slot tradeoff is justified. + +## License + +MIT diff --git a/skills/memory-continuity/SKILL.md b/skills/memory-continuity/SKILL.md index 4acc77b..57d0825 100644 --- a/skills/memory-continuity/SKILL.md +++ b/skills/memory-continuity/SKILL.md @@ -1,122 +1,236 @@ --- name: memory-continuity -description: Preserve short-term working continuity for OpenClaw agents when recent in-flight work gets lost after gateway interruption/restart, model fallback or unavailability, /new or fresh sessions, context compaction, or silent execution-agent reporting gaps. Use when you need memory/CURRENT_STATE.md, dual reporting discipline, continuity doctor checks, or repair of continuity drift across agent workspaces. +description: > + 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 +# memory-continuity -Use this skill to prevent agents from forgetting what is currently in flight when continuity breaks in practical ways: gateway interruption/restart, model fallback/unavailability, `/new` or fresh sessions, context compaction, or worker results not being surfaced upward in time. +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. -Use `memory/CURRENT_STATE.md` as a small overwrite-oriented workbench, not as a journal. +## Positioning -## Core rules +This skill is **not** the whole long-term architecture. -- Ensure every agent workspace has `memory/CURRENT_STATE.md` -- Keep `CURRENT_STATE.md` small - - main: target 25-40 lines, hard cap 50 - - other agents: target 15-25 lines, hard cap 30 -- Required sections: - - `In Flight` - - `Blocked / Waiting` - - `Recently Finished` - - `Next` - - `Reset Summary` -- Update only on state changes, not on a timer -- Remove stale items instead of endlessly appending +It is the current: +- **behavior contract** for agents +- **fallback implementation** when no plugin is installed +- **human-readable protocol** for maintaining working-state continuity -## Minimal JIRA-like workflow +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. -Keep the workflow small. Use these task states only: -- `planned` -- `dispatching` -- `in_progress` -- `blocked` -- `reviewing` -- `done` +## Why this exists -State meaning: -- `planned`: task exists and has been defined -- `dispatching`: main has initiated delegation, but does not yet have enough evidence that the worker truly launched -- `in_progress`: worker/session has visible execution evidence -- `blocked`: task cannot safely proceed right now (including launch failure, stalled worker, model failure, auth/tool issues) -- `reviewing`: deliverable exists and main is validating it -- `done`: main has accepted the result and updated Tao +OpenClaw already has native systems for: +- transcript persistence +- compaction summaries +- pre-compaction `memoryFlush` +- session-aware `memory_search` -Evidence rule: -- Do not upgrade a task state without an evidence point. -- Good evidence points include: non-empty worker session history, worker accepted/milestone reply, commit, branch, PR, release, or runtime log. -- `sessions_spawn accepted` alone is not enough to claim real progress. +Those are valuable, but they answer a different question. -Timeout rules: -- If a worker has no first visible response/evidence within 10 minutes after dispatch, mark the task `blocked` with reason `launch failure`. -- If a worker has an ETA and passes that ETA without a milestone, mark the task `blocked` with reason `stalled`. -- Silence is not neutral; unexplained silence is a process failure signal. +They help with: +- what was discussed before? +- what knowledge or facts were written down? -## Dual reporting protocol +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? -### Worker → main -Execution agents must report to main at: -- accepted -- blocked -- milestone -- done -- model/environment abnormal +That is why `CURRENT_STATE.md` exists. -Preferred reply format: -- `status` -- `summary` -- `evidence` -- `risk` -- `next` +## Source of truth -### main → Tao -Main must report to Tao at: -- task formally started -- worker truly in progress (not merely spawn-accepted) -- blocked -- milestone reached -- task/phase completed +The source of truth for working-state continuity is: +- `memory/CURRENT_STATE.md` -Preferred Tao update format: -- who -- status -- output -- next +This file should stay: +- short +- structured +- overwrite-oriented +- readable by both humans and agents -Ordering rule: -- When a worker reports milestone/completion/blocker, first update `CURRENT_STATE.md`, then update Tao, then continue with review/commit/next dispatch. -- If no evidence point exists yet (sessionKey with trace / commit / branch / PR / log), do not claim work has already started; say it is about to start. +It is a **checkpoint**, not a journal. -## When to use the doctor -Run `scripts/continuity_doctor.py` when: -- OpenClaw was upgraded -- gateway restarted and continuity feels suspicious -- an agent seems to have lost short-term context -- you need to confirm `CURRENT_STATE.md` coverage across workspaces +## File layout -## How to use the doctor -From the main workspace: - -```bash -python3 skills/memory-continuity/scripts/continuity_doctor.py \\ - --main-workspace /Users/taodeng/.openclaw/workspace/main \ - --agents-root /Users/taodeng/.openclaw/workspaces +```text +$WORKSPACE/ +├── memory/ +│ ├── CURRENT_STATE.md # live workbench (overwrite, never append-log) +│ └── session_archive/ # optional frozen snapshots +│ ├── 2026-03-12_14-30.md +│ └── ... ``` -The doctor checks: -- main `memory/CURRENT_STATE.md` exists -- all agent workspaces have `memory/CURRENT_STATE.md` -- required sections exist -- line-count caps are respected -- `AGENTS.md` still contains continuity + dual reporting rules +--- -## Repair strategy -If drift is found: -1. Restore/create missing `memory/CURRENT_STATE.md` -2. Restore continuity guidance in `AGENTS.md` -3. Re-run doctor -4. Only then investigate deeper behavioral failures +## MANDATORY PROTOCOL -## References -- For template and limits: read `references/template.md` -- For doctor semantics and PASS/WARN/FAIL meanings: read `references/doctor-spec.md` +### 1. On session start or recovery-like prompts + +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 + +If no active work exists: +- normal conversation flow is fine + +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 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 | + +### 4. Keep the checkpoint small + +`CURRENT_STATE.md` should usually stay under about 40 lines and be readable in +15 seconds. + +If it grows too long, compress it. +If it turns into a diary, you are using the wrong file. + +### 5. Result surfacing rule + +If you are a sub-agent or execution agent: +- write unreported outcomes into `## Unsurfaced Results` +- do not assume the main agent has already forwarded them + +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 + +--- + +## CURRENT_STATE.md Template + +```markdown +# Current State +> Last updated: [ISO timestamp] + +## Objective +[One sentence: what are we trying to accomplish] + +## Current Step +[What step are we on, what was the last thing completed] + +## Key Decisions +- [Decision 1: what was decided and why, max 3 items] + +## Next Action +[Exactly what should happen next] + +## Blockers +[What is preventing progress, or "None"] + +## Unsurfaced Results +[Results from sub-agents or tools not yet shown to user, or "None"] +``` + +### 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. + +--- + +## Continuity Doctor (optional) + +Run `scripts/continuity_doctor.py` to check workspace health: + +```bash +python3 scripts/continuity_doctor.py --workspace /path/to/workspace +``` + +The doctor reports only. It does **not** auto-repair. + +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 +- 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 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/skills/memory-continuity/references/doctor-spec.md b/skills/memory-continuity/references/doctor-spec.md index 0f1caf2..eb8d7e1 100644 --- a/skills/memory-continuity/references/doctor-spec.md +++ b/skills/memory-continuity/references/doctor-spec.md @@ -1,41 +1,90 @@ -# continuity doctor spec +# Continuity Doctor — Specification -## PASS -The checked item exists and matches the required structure. +## Purpose -## WARN -The item exists but is drifting: -- file too long -- required text partly missing -- structure present but not ideal +The continuity doctor is a diagnostic tool that checks whether the +memory-continuity protocol is being followed correctly in a workspace. +It reports problems but does **not** auto-fix them. -## FAIL -The item is missing or materially broken: -- missing CURRENT_STATE.md -- missing required sections -- missing continuity rules in AGENTS.md +## Design philosophy -## Minimal checks -1. `main/memory/CURRENT_STATE.md` exists -2. each agent workspace has `memory/CURRENT_STATE.md` -3. every `CURRENT_STATE.md` contains: - - `## In Flight` - - `## Blocked / Waiting` - - `## Recently Finished` - - `## Next` - - `## Reset Summary` -4. main `AGENTS.md` contains continuity guidance, minimal JIRA-like workflow markers, and dual reporting protocol markers -5. line-count caps are respected +- **Diagnose, don't repair.** Automated repair of state files is dangerous + 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. -## Runtime/process checks to add later -These are not fully implemented yet, but are part of the intended workflow: -- detect `dispatching` tasks that never produce a worker trace -- treat no first response within 10 minutes as `blocked (launch failure)` -- treat missed milestone ETA as `blocked (stalled)` -- ensure main does not claim `in_progress` without evidence +## Checks performed -## Suggested actions on failure -- create missing files from template -- restore missing AGENTS continuity section -- trim oversized CURRENT_STATE files -- rerun doctor after repair +### 1. Existence check +- Does `memory/CURRENT_STATE.md` exist? +- Severity: CRITICAL if missing (no deterministic recovery point) + +### 2. Staleness check +- When was `CURRENT_STATE.md` last modified? +- 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? +- Severity: WARNING for missing sections, INFO/WARNING for unresolved placeholders depending on severity + +### 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 likely still needs to review or forward those results. +- Severity: WARNING + +### 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 + +### 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 +``` + +## Future extensions (not yet implemented) + +- Multi-workspace scan (check all sub-agent workspaces) +- JSON output mode for programmatic consumption +- Integration with scheduled health checks +- More transcript-aware recovery-priority detection +- Validation support for future lifecycle-plugin checkpoints diff --git a/skills/memory-continuity/references/template.md b/skills/memory-continuity/references/template.md index 229118c..938bb01 100644 --- a/skills/memory-continuity/references/template.md +++ b/skills/memory-continuity/references/template.md @@ -1,51 +1,28 @@ -# CURRENT_STATE template +# Current State +> Last updated: [ISO timestamp] -## main agent (expanded) +## Objective +[One sentence: what are we trying to accomplish] -```md -# CURRENT_STATE +## Current Step +[What step are we on, what was the last thing completed] -_Last updated: YYYY-MM-DD HH:MM Australia/Brisbane_ +## Key Decisions +- None -## In Flight -- [status] task — owner — latest milestone +## Next Action +[Exactly what should happen next] -## Blocked / Waiting -- item — blocker / waiting on +## Blockers +None -## Recently Finished -- result — why it still matters now +## Unsurfaced Results +None -## Next -- next action +--- -## Reset Summary -- one short paragraph explaining what matters if a new session starts now -``` - -Capacity: -- target 25-40 lines -- hard cap 50 lines -- In Flight max 5 -- Blocked / Waiting max 5 -- Recently Finished max 3 -- Next max 5 - -## other agents (standard) -Use the same template, but keep it smaller. - -Capacity: -- target 15-25 lines -- hard cap 30 lines -- In Flight max 3 -- Blocked / Waiting max 3 -- Recently Finished max 2 -- Next max 3 - -## Allowed status values -- planned -- dispatched -- in_progress -- blocked -- reviewing -- done +## 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.