memory-continuity/README.md

memory-continuity

Current release: v2.3.0

OpenClaw lifecycle plugin for short-term working continuity. Preserves structured in-flight work state across /new, reset, gateway restarts, model fallback, and context compaction.

Why this plugin?

There are feature-rich memory plugins out there (vector search, semantic dedup, smart extraction). We took a different path:

• Zero dependency — no embedding API, no vector DB, no external services
• Plain files — data is markdown, human-readable, editable, greppable
• Hook-driven — doesn't rely on model behavior, works with any model
• Backup = copy — cp / scp / rsync is your entire backup strategy
• Migrate in seconds — copy files to new host, done. No re-indexing, no model binding
• Upgrade-proof — doesn't occupy the contextEngine slot, doesn't depend on OpenClaw internals
• Native-consistent — aligns with OpenClaw's memory/ file conventions

If what you need is "don't lose work across sessions" rather than "semantic search over 100k memories", this plugin is for you.

What problem does this solve?

OpenClaw already preserves transcripts, compaction summaries, memory files, and session memory search. But those don't 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 plugin solves.

One-line summary:

• long-term memory = what you know
• memory continuity = what you are doing right now

How it works

The plugin uses OpenClaw lifecycle hooks to automatically save and restore working state — no model cooperation needed.

Hook	What it does
before_agent_start	Reads memory/CURRENT_STATE.md and injects it into the agent's system context
before_compaction	Injects state before compaction so it survives context compression
before_reset	Archives current state to session_archive/ before /new
agent_end	Auto-extracts working state from conversation if no explicit state exists
session_end	Ensures CURRENT_STATE.md exists for future sessions

Because state injection happens at the hook level (before the model sees anything), it works with any model — GPT-4o, MiniMax, Claude, etc.

Quick Start

Install

# Clone the plugin
git clone https://github.com/dtzp555-max/memory-continuity.git

# Run the installer
cd memory-continuity
bash scripts/post-install.sh

The installer will:

1. Copy the plugin to ~/.openclaw/extensions/memory-continuity/
2. Add the plugin entry to ~/.openclaw/openclaw.json
3. Add memory-continuity to plugins.allow (trust list)
4. Add install record to plugins.installs (provenance tracking)
5. Restart the gateway

No npm install, no API keys, no external database.

Verify

openclaw gateway restart 2>&1 | grep memory-continuity
# Should show: [memory-continuity] Plugin registered successfully

Test

1. Tell your agent something memorable (e.g., "I'll tell you a secret: Ethan is super kid")
2. Send /new to reset the session
3. Ask "what was the secret?" or "我们刚才聊到哪了"
4. The agent should immediately surface the recovered state

Configuration

The plugin works with zero configuration. Optional settings in openclaw.json:

{
  "plugins": {
    "allow": ["memory-continuity"],
    "entries": {
      "memory-continuity": {
        "enabled": true,
        "hooks": {
          "allowPromptInjection": true
        },
        "config": {
          "maxStateLines": 50,
          "archiveOnNew": true,
          "autoExtract": true
        }
      }
    }
  }
}

Option	Default	Description
maxStateLines	50	Max lines for CURRENT_STATE.md
archiveOnNew	true	Archive state to session_archive/ before /new
autoExtract	true	Auto-extract state from conversation at session end

The checkpoint file

The plugin maintains one file: $WORKSPACE/memory/CURRENT_STATE.md

# Current State
> Last updated: 2026-03-15T14:00: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)

## Next Action
Implement POST /auth/refresh endpoint

## Blockers
None

## Unsurfaced Results
None

This file is:

• Overwritten, not appended (it's a checkpoint, not a journal)
• Human-readable plain markdown
• Portable — just copy the file to backup or migrate
• Model-agnostic — injected via hooks, not dependent on model behavior

Backup & Migration

# Backup
cp $WORKSPACE/memory/CURRENT_STATE.md /backup/

# Migrate to another machine
scp -r ~/.openclaw/extensions/memory-continuity/ newhost:~/.openclaw/extensions/
scp $WORKSPACE/memory/CURRENT_STATE.md newhost:$WORKSPACE/memory/

No database, no vector embeddings, no API keys to transfer.

OpenClaw 升级后恢复

OpenClaw 升级（npm update -g openclaw）不会覆盖 ~/.openclaw/openclaw.json 用户配置。但如果插件行为异常，按以下步骤排查和恢复：

快速诊断

# 检查插件是否加载
openclaw gateway restart 2>&1 | grep memory-continuity
# 应输出: [memory-continuity] Plugin registered successfully

# 检查配置是否完整
cat ~/.openclaw/openclaw.json | grep -A2 memory-continuity

常见故障与恢复

症状	原因	恢复方法
启动日志无 Plugin registered	插件文件缺失或配置丢失	重跑 bash scripts/post-install.sh
plugins.allow is empty 警告	openclaw.json 中 plugins.allow 被清空	添加 "plugins.allow": ["memory-continuity"]
loaded without provenance 警告	plugins.installs 记录丢失	添加 "plugins.installs": {"memory-continuity": {"source": "path"}}
新版本改了钩子 API	OpenClaw breaking change	查看 CHANGELOG，更新 index.js
状态不恢复但无报错	Session 缓存了旧的 skillsSnapshot	/new 开新 session，或重跑 post-install.sh（会清缓存）

一键恢复

出现任何问题，重跑安装脚本即可（幂等，可重复执行）：

cd ~/.openclaw/projects/memory-continuity   # 或你 clone 的位置
git pull                                     # 拉取最新版本
bash scripts/post-install.sh                 # 重新安装 + 重启 gateway

升级前备份（推荐）

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak

Architecture: Plugin vs Skill

Previous versions (v0.x) shipped as a skill — a markdown file that asked the model to read/write CURRENT_STATE.md. This was unreliable because models could ignore the instructions.

v2.0 is a lifecycle plugin that uses OpenClaw hooks. The key difference:

	Skill (v0.x)	Plugin (v2.0)
State injection	Model must read the file	Hook injects automatically
State saving	Model must write the file	Hook saves automatically
Model dependency	Requires model cooperation	Model-agnostic
Reliability	Varies by model	Consistent

The skill (SKILL.md) is retained as documentation and fallback protocol.

Repository layout

memory-continuity/
├── openclaw.plugin.json           # Plugin manifest
├── index.js                       # Plugin entry point (hooks)
├── SKILL.md                       # Behavior contract / protocol docs
├── README.md
├── LICENSE
├── plugin/
│   └── lifecycle-prototype.ts     # Original prototype (reference)
├── references/
│   ├── template.md
│   ├── doctor-spec.md
│   └── phase2-hook-validation.md
└── scripts/
    ├── post-install.sh            # Automated installer
    └── continuity_doctor.py       # Health check

Design principles

1. Files are the source of truth — plain markdown, no database
2. Hooks over prompts — don't rely on model behavior
3. Zero external dependencies — no API keys, no vector DB
4. Portable and backupable — cp is your backup tool
5. Complements native OpenClaw memory — does not replace it

License

MIT