taodeng/memory-continuity
1
0
Fork 0
mirror of https://github.com/dtzp555-max/memory-continuity.git synced 2026-07-21 21:15:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: sync skill docs with lifecycle plugin plan

Browse Source
This commit is contained in:
taodeng
2026-03-13 05:11:07 +10:00
parent 993db79325
commit ffec85f66d
4 changed files with 321 additions and 187 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+116 -93
View File
@@ -1,44 +1,65 @@
# memory-continuity # memory-continuity
OpenClaw skill for **short-term working continuity** — so your agent can pick up OpenClaw skill for **short-term working continuity** — so an agent can recover
exactly where it left off after a gateway crash, `/new`, model fallback, or structured in-flight work state after `/new`, reset, gateway interruption,
context compaction. model fallback, or compaction.
## What problem does this solve? ## What problem does this solve?
When your gateway dies mid-conversation, or you hit `/new` to start fresh, or OpenClaw already preserves a lot:
the model falls back to a different provider — your agent loses its working - transcripts
context. Long-term memory can tell it *what it knows*, but not *what it was - compaction summaries
doing*. This skill fills that gap. - memory files
- session memory search
**One-line summary:** Long-term memory = what you know. This skill = what you But those do not always answer the most operational question:
are doing right now.
> 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 ## Quick Start
### Install ### Install
```bash ```bash
# Go to your OpenClaw workspace skills directory
cd ~/.openclaw/workspace/skills/ cd ~/.openclaw/workspace/skills/
# Clone
git clone https://github.com/dtzp555-max/memory-continuity.git 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 ### Test the current skill version
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?"*
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 ### 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 python3 scripts/continuity_doctor.py --workspace ~/.openclaw/workspace
``` ```
Sample output: ## How the current skill version works
```
Continuity Doctor — scanning: /Users/you/.openclaw/workspace
============================================================
[OK] memory/CURRENT_STATE.md exists The skill defines a discipline around one file:
[OK] CURRENT_STATE.md is fresh (0.3h old) - `memory/CURRENT_STATE.md`
[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
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 checkpoint shape
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:
```markdown ```markdown
# Current State # Current State
@@ -97,75 +103,92 @@ None
None None
``` ```
The entire file is designed to be read in 15 seconds. It is overwritten (not ## Recovery rules
appended) on every update, keeping it permanently short.
## 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 | ## Relationship to native OpenClaw features
|---|---|---|
| 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 |
These layers are complementary. This skill has **zero dependency** on any ### Native OpenClaw already handles
database or external memory plugin. It works with plain markdown files that - transcript persistence
live in your workspace and can be backed up with `git` or `cp`. - 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/ memory-continuity/
├── SKILL.md # Core skill (loaded by OpenClaw) ├── SKILL.md
├── README.md # This file ├── README.md
├── LICENSE # MIT ├── LICENSE
├── references/ ├── references/
│ ├── template.md # CURRENT_STATE.md blank template │ ├── template.md
│ └── doctor-spec.md # Doctor check specifications │ └── doctor-spec.md
└── scripts/ └── 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/ $WORKSPACE/
└── memory/ └── memory/
├── CURRENT_STATE.md # Live workbench (overwritten each update) ├── CURRENT_STATE.md
└── session_archive/ # Timestamped snapshots from past sessions └── session_archive/
├── 2026-03-12_14-30.md
└── ...
``` ```
## Design principles ## Design principles
1. **Zero dependencies.** No database, no API, no npm packages. Just files. 1. **Files are the source of truth**
2. **Backup = copy.** The entire state is in `memory/`. Back it up however you 2. **Structured checkpoint beats free-form recollection**
back up your workspace. 3. **Recovery must prefer truth over confident guessing**
3. **Overwrite, don't append.** CURRENT_STATE.md is a workbench, not a journal. 4. **This complements native OpenClaw memory; it does not replace it**
It stays short because it is replaced on every update. 5. **Read access is helpful, but should not be the only long-term path**
4. **Diagnose, don't auto-repair.** The doctor script flags problems for you to 6. **The primary plugin direction should coexist with other ecosystem plugins such as `lossless-claw`**
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).
## 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: ### Phase 2
- SKILL.md protocol with discipline rules Build a **standard lifecycle plugin** as the primary runtime path:
- CURRENT_STATE.md template - startup recovery behavior
- Continuity doctor diagnostic script - `/new` checkpointing
- Session archive on `/new` - compaction-boundary checkpointing
- end-of-run safety writes
Planned: ### Future option
- Plugin version with `command:new` and `before_agent_start` hooks Evaluate a ContextEngine variant later only if the slot tradeoff is justified.
(for guaranteed save/restore without relying on agent self-discipline)
- More real-world validation across different gateway configurations
- Sub-agent continuity handover protocol
## License ## License
SKILL.md
+151 -74
View File
@@ -1,37 +1,77 @@
--- ---
name: memory-continuity name: memory-continuity
description: > description: >
Short-term working continuity for OpenClaw agents. Preserves in-flight state Short-term working continuity for OpenClaw agents. Preserves structured
across gateway restarts, /new, model fallback, and context compaction. in-flight work state across gateway restarts, /new, reset, model fallback,
Use this skill whenever an agent needs to survive session breaks without and context compaction. This skill is the human-readable protocol and
losing what it was doing. Triggers on: session start, /new, context recovery, fallback layer for working-state recovery; it complements native OpenClaw
"where were we", "continue", resuming work, or any situation where recent memory, compaction, and session memory search rather than replacing them.
working state may have been lost. This is NOT a long-term memory system — Use when an agent needs to survive session breaks without losing what it was
it is a crash-recovery workbench. doing.
--- ---
# memory-continuity # memory-continuity
Lightweight continuity layer that keeps a single overwrite-oriented state file Lightweight continuity layer built around a single overwrite-oriented state file
(`memory/CURRENT_STATE.md`) so any agent can pick up exactly where it left off (`memory/CURRENT_STATE.md`). Its job is simple: keep a compact, structured
after a restart, `/new`, gateway crash, model fallback, or context compaction. 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 ## Why this exists
Long-term memory (vector DB, markdown journals) stores *what you know*. OpenClaw already has native systems for:
This skill stores *what you are doing right now*. They solve different problems. - 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 Those are valuable, but they answer a different question.
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. 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 ## File layout
``` ```text
$WORKSPACE/ $WORKSPACE/
├── memory/ ├── memory/
│ ├── CURRENT_STATE.md # THE workbench (overwritten, never appended) │ ├── CURRENT_STATE.md # live workbench (overwrite, never append-log)
│ └── session_archive/ # compressed snapshots from past sessions │ └── session_archive/ # optional frozen snapshots
│ ├── 2026-03-12_14-30.md │ ├── 2026-03-12_14-30.md
│ └── ... │ └── ...
``` ```
@@ -40,53 +80,88 @@ $WORKSPACE/
## MANDATORY PROTOCOL ## MANDATORY PROTOCOL
### 1. On every session start ### 1. On session start or recovery-like prompts
``` If `memory/CURRENT_STATE.md` exists:
IF memory/CURRENT_STATE.md exists: 1. read it
READ it 2. determine whether it contains meaningful active work
Tell user: "Last session we were working on [Objective]. We reached [Current Step]. Want to continue?" 3. if active work exists and the user is asking to continue / recover / resume,
WAIT for user confirmation before proceeding **surface the recovered state before generic greeting or chit-chat**
ELSE: 4. prefer truth over guessing
Create memory/CURRENT_STATE.md with empty template (see below)
```
### 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 | | Trigger | Why |
|---|---| |---|---|
| User confirms a decision | Decisions are the hardest thing to reconstruct | | User confirms a decision | Decisions are hard to reconstruct later |
| A task step completes | Marks progress so next session knows where to start | | A concrete task step completes | Marks true progress for recovery |
| An error or blocker appears | Prevents the next session from hitting the same wall | | A blocker or error appears | Prevents repeated failure after reset |
| Before any tool call that might take long | If gateway dies during the call, state is already saved | | Before long-running or risky tool work | Preserves a recovery point before interruption |
| User says "let's stop here" or similar | Explicit save point | | Before `/new` / reset-like boundary | Prevents deliberate context reset from dropping work state |
| Every ~10 turns of substantive conversation | Periodic checkpoint against silent context loss | | 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 ### 4. Keep the checkpoint small
stay under 40 lines. If you find yourself writing more, you are journaling,
not checkpointing. Stop and compress.
### 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 ### 5. Result surfacing rule
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
If you are a sub-agent or execution agent: If you are a sub-agent or execution agent:
- Before exiting, write your key results into CURRENT_STATE.md under `## Unsurfaced Results` - write unreported outcomes into `## Unsurfaced Results`
- The main agent MUST check this section on startup and relay findings to the user - 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"] [Results from sub-agents or tools not yet shown to user, or "None"]
``` ```
**Rules for this template:** ### Template rules
- Every field is mandatory. Write "None" rather than omitting a section. - Every field is mandatory. Use `None` rather than omission.
- `Objective` and `Next Action` are the two most critical fields. If you can - `Objective` and `Next Action` are the two most critical fields.
only save two things before a crash, save these. - `Key Decisions` should stay short; move older material to long-term memory.
- `Key Decisions` caps at 3 items. Older decisions belong in long-term memory, - `Unsurfaced Results` should be explicit, not implied.
not here. - If `Objective` is empty / placeholder / idle, recovery should not pretend there is active work.
- The entire file should be readable in 15 seconds. If it takes longer, trim it.
--- ---
@@ -133,27 +207,30 @@ Run `scripts/continuity_doctor.py` to check workspace health:
python3 scripts/continuity_doctor.py --workspace /path/to/workspace python3 scripts/continuity_doctor.py --workspace /path/to/workspace
``` ```
It checks: The doctor reports only. It does **not** auto-repair.
- 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. 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 ## What this skill is NOT
- Not a long-term memory system (use OpenClaw's native markdown memory or LanceDB for that) - Not a long-term memory system
- Not a conversation log or journal (CURRENT_STATE.md is overwritten, not appended) - Not a replacement for OpenClaw compaction
- Not a task manager (use OpenSpec or tasks.md for project planning) - Not a replacement for `memoryFlush`
- Not dependent on any external database (works with plain files only) - 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 ## Compatibility
- Works with any OpenClaw agent (main or sub-agent) - Works as a plain-skill fallback today
- No external dependencies (no npm install, no API keys, no database) - Compatible with main agents and subagents when they can maintain the file
- Backup: `git add memory/` or `cp -r memory/ /backup/` — that is the entire disaster recovery plan - Designed to evolve toward a **standard lifecycle plugin** as the primary runtime path
- Can coexist with memory-lancedb-pro, hippocampus, or any other memory skill - Intentionally avoids depending on the exclusive `contextEngine` slot as the default architecture
references/doctor-spec.md
+45 -19
View File
@@ -9,50 +9,74 @@ It reports problems but does **not** auto-fix them.
## Design philosophy ## Design philosophy
- **Diagnose, don't repair.** Automated repair of state files is dangerous - **Diagnose, don't repair.** Automated repair of state files is dangerous
because incorrect "fixes" can overwrite valid state. The doctor flags because incorrect fixes can overwrite valid state.
issues for human or agent review.
- **Fast and offline.** No API calls, no database queries. Reads files only. - **Fast and offline.** No API calls, no database queries. Reads files only.
- **Exit codes matter.** 0 = healthy, 1 = warnings found, 2 = critical issues. - **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 ## Checks performed
### 1. Existence check ### 1. Existence check
- Does `memory/CURRENT_STATE.md` exist? - Does `memory/CURRENT_STATE.md` exist?
- Severity: CRITICAL if missing (no recovery possible) - Severity: CRITICAL if missing (no deterministic recovery point)
### 2. Staleness check ### 2. Staleness check
- When was `CURRENT_STATE.md` last modified? - 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 - Severity: WARNING
### 3. Template compliance ### 3. Template compliance
- Does the file contain all mandatory sections? - Does the file contain all mandatory sections?
(Objective, Current Step, Key Decisions, Next Action, Blockers, Unsurfaced Results) (`Objective`, `Current Step`, `Key Decisions`, `Next Action`, `Blockers`, `Unsurfaced Results`)
- Are any sections still showing placeholder text like `[One sentence: ...]`? - Are any sections still showing placeholder text?
- Severity: WARNING for missing sections, INFO for 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? - 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 - Severity: WARNING
### 5. Archive consistency ### 6. Archive consistency
- Are there files in `memory/session_archive/` ? - Are there files in `memory/session_archive/`?
- Does the newest archive have a different Objective than CURRENT_STATE.md? - Does the newest archive differ significantly from `CURRENT_STATE.md`?
(This is expected if the user switched tasks, but worth flagging.) (This may be expected after task switches, but is worth flagging.)
- Severity: INFO - Severity: INFO
### 6. Conflict detection (optional, if tasks file exists) ### 7. Recovery-priority hygiene (best-effort)
- If a `tasks.md` or `openspec/` directory exists, does the Objective in - If workspace/session evidence suggests a recovery scenario recently occurred,
CURRENT_STATE.md align with any active task? did the agent still prefer generic greeting over recovered work state?
- Severity: INFO (alignment is nice-to-have, not mandatory) - 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 ## Output format
``` ```text
[CRITICAL] memory/CURRENT_STATE.md does not exist [CRITICAL] memory/CURRENT_STATE.md does not exist
[WARNING] CURRENT_STATE.md is stale (last modified 2h ago, session ran 30m ago) [WARNING] CURRENT_STATE.md is stale (last modified 2h ago, session ran 30m ago)
[WARNING] Unsurfaced Results section is not empty — review needed [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?) [INFO] Archive objective differs from current objective (task switch?)
[OK] Template compliance: all sections present [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) - Multi-workspace scan (check all sub-agent workspaces)
- JSON output mode for programmatic consumption - 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
references/template.md
+9 -1
View File
@@ -8,7 +8,7 @@
[What step are we on, what was the last thing completed] [What step are we on, what was the last thing completed]
## Key Decisions ## Key Decisions
- None yet - None
## Next Action ## Next Action
[Exactly what should happen next] [Exactly what should happen next]
@@ -18,3 +18,11 @@ None
## Unsurfaced Results ## Unsurfaced Results
None 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.