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

docs: align memory continuity skill with lifecycle plugin plan

Browse Source
This commit is contained in:
taodeng
2026-03-12 22:42:50 +10:00
parent ef4d965e44
commit c688ef5239
4 changed files with 510 additions and 175 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/memory-continuity/README.md
+195
View File
@@ -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
skills/memory-continuity/SKILL.md
+211 -97
View File
@@ -1,122 +1,236 @@
--- ---
name: memory-continuity 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` It is the current:
- Keep `CURRENT_STATE.md` small - **behavior contract** for agents
- main: target 25-40 lines, hard cap 50 - **fallback implementation** when no plugin is installed
- other agents: target 15-25 lines, hard cap 30 - **human-readable protocol** for maintaining working-state continuity
- 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
## 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: ## Why this exists
- `planned`
- `dispatching`
- `in_progress`
- `blocked`
- `reviewing`
- `done`
State meaning: OpenClaw already has native systems for:
- `planned`: task exists and has been defined - transcript persistence
- `dispatching`: main has initiated delegation, but does not yet have enough evidence that the worker truly launched - compaction summaries
- `in_progress`: worker/session has visible execution evidence - pre-compaction `memoryFlush`
- `blocked`: task cannot safely proceed right now (including launch failure, stalled worker, model failure, auth/tool issues) - session-aware `memory_search`
- `reviewing`: deliverable exists and main is validating it
- `done`: main has accepted the result and updated Tao
Evidence rule: Those are valuable, but they answer a different question.
- 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.
Timeout rules: They help with:
- If a worker has no first visible response/evidence within 10 minutes after dispatch, mark the task `blocked` with reason `launch failure`. - what was discussed before?
- If a worker has an ETA and passes that ETA without a milestone, mark the task `blocked` with reason `stalled`. - what knowledge or facts were written down?
- Silence is not neutral; unexplained silence is a process failure signal.
## 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 That is why `CURRENT_STATE.md` exists.
Execution agents must report to main at:
- accepted
- blocked
- milestone
- done
- model/environment abnormal
Preferred reply format: ## Source of truth
- `status`
- `summary`
- `evidence`
- `risk`
- `next`
### main → Tao The source of truth for working-state continuity is:
Main must report to Tao at: - `memory/CURRENT_STATE.md`
- task formally started
- worker truly in progress (not merely spawn-accepted)
- blocked
- milestone reached
- task/phase completed
Preferred Tao update format: This file should stay:
- who - short
- status - structured
- output - overwrite-oriented
- next - readable by both humans and agents
Ordering rule: It is a **checkpoint**, not a journal.
- 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.
## When to use the doctor ## File layout
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
## How to use the doctor ```text
From the main workspace: $WORKSPACE/
├── memory/
```bash │ ├── CURRENT_STATE.md # live workbench (overwrite, never append-log)
python3 skills/memory-continuity/scripts/continuity_doctor.py \\ │ └── session_archive/ # optional frozen snapshots
--main-workspace /Users/taodeng/.openclaw/workspace/main \ │ ├── 2026-03-12_14-30.md
--agents-root /Users/taodeng/.openclaw/workspaces │ └── ...
``` ```
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 ## MANDATORY PROTOCOL
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
## References ### 1. On session start or recovery-like prompts
- For template and limits: read `references/template.md`
- For doctor semantics and PASS/WARN/FAIL meanings: read `references/doctor-spec.md` 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
skills/memory-continuity/references/doctor-spec.md
+84 -35
View File
@@ -1,41 +1,90 @@
# continuity doctor spec # Continuity Doctor — Specification
## PASS ## Purpose
The checked item exists and matches the required structure.
## WARN The continuity doctor is a diagnostic tool that checks whether the
The item exists but is drifting: memory-continuity protocol is being followed correctly in a workspace.
- file too long It reports problems but does **not** auto-fix them.
- required text partly missing
- structure present but not ideal
## FAIL ## Design philosophy
The item is missing or materially broken:
- missing CURRENT_STATE.md
- missing required sections
- missing continuity rules in AGENTS.md
## Minimal checks - **Diagnose, don't repair.** Automated repair of state files is dangerous
1. `main/memory/CURRENT_STATE.md` exists because incorrect fixes can overwrite valid state.
2. each agent workspace has `memory/CURRENT_STATE.md` - **Fast and offline.** No API calls, no database queries. Reads files only.
3. every `CURRENT_STATE.md` contains: - **Exit codes matter.** 0 = healthy, 1 = warnings found, 2 = critical issues.
- `## In Flight` - **Working-state focus.** The doctor validates active-work recovery hygiene,
- `## Blocked / Waiting` not long-term memory quality.
- `## 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
## Runtime/process checks to add later ## Checks performed
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
## Suggested actions on failure ### 1. Existence check
- create missing files from template - Does `memory/CURRENT_STATE.md` exist?
- restore missing AGENTS continuity section - Severity: CRITICAL if missing (no deterministic recovery point)
- trim oversized CURRENT_STATE files
- rerun doctor after repair ### 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
skills/memory-continuity/references/template.md
+20 -43
View File
@@ -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 Step
# CURRENT_STATE [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 ## Next Action
- [status] task — owner — latest milestone [Exactly what should happen next]
## Blocked / Waiting ## Blockers
- item — blocker / waiting on None
## Recently Finished ## Unsurfaced Results
- result — why it still matters now None
## Next ---
- next action
## Reset Summary ## Template notes
- one short paragraph explaining what matters if a new session starts now - 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.
Capacity: - In recovery scenarios, agents should surface this state before generic greetings when active work is present.
- 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