openclaw-memory-dreaming（OpenClaw 记忆 dreaming）

Memory Dreaming

Agent-native memory and dreaming framework. Plain Markdown and JSON — no RAG, no vector store, no graph database. Just files your human can read and edit.

References (load when needed): - references/architecture.md — data model, biological inspiration, design decisions - references/dream-cycle.md — full dream cycle procedure with examples - references/cold-start.md — starting from zero memories - references/cron-templates.md — ready-to-use OpenClaw cron definitions

Setup

1. Copy scripts to your workspace

cp skills/memory-dreaming/scripts/*.js scripts/

Scripts use path.resolve(__dirname, '..') for workspace root — they must live in <workspace>/scripts/.

2. Bootstrap (if you have an existing MEMORY.md)

node scripts/memory-bootstrap.js          # seed memory-meta.json
node scripts/conversation-archive.js --discover  # see available channels

Starting from scratch? See references/cold-start.md.

3. Set up conversation archiving (optional)

Create archives/archive-config.json to label your groups:

{
  "agentName": "YourName",
  "groups": { "<group-id>": { "name": "my-group", "label": "My Group" } },
  "topicNames": { "<group-id>": { "1": "General" } }
}

Then archive and summarise:

node scripts/conversation-archive.js --all
node scripts/conversation-summarise.js --all

Two Layers

Layer 1: Core Memory

Your curated knowledge — facts, preferences, decisions, people.

Layer 2: Conversational Memory

Context from group chats, channels, topics — archived and summarised.

Memory Tiers

Structural entries (IPs, people, URLs, passwords) never decay below 0.3.

Decay Formula

baseDecay    = 1.0 - (daysSinceCreated / maxAgeDays)
recallBoost  = min(recallCount × 0.05, 0.5)
recencyBoost = lastRecalled ≤7d → 0.2 | ≤30d → 0.1 | else → 0
decayScore   = clamp(base + recall + recency, 0.0, 1.0)

Scripts (6)

Core Memory

Conversation Memory

Usage Examples

# Core memory
node scripts/memory-decay.js --verbose
node scripts/memory-recall-logger.js --query "dev server IP" --matches "Dev server: user@203.0.113.10"
node scripts/memory-supersede.js --old "Status: pending" --new "Status: accepted"

# Conversation memory
node scripts/conversation-archive.js --discover     # list available sessions
node scripts/conversation-archive.js --all           # archive everything
node scripts/conversation-archive.js --channel telegram --group my-group
node scripts/conversation-summarise.js --all         # summarise all archived
node scripts/conversation-summarise.js --force       # re-summarise everything

Daily Workflow

Every session

1. Load MEMORY.md for context.
2. After searching memory, log recalls:

   node scripts/memory-recall-logger.js --query "<search>" --matches "<matched line>"

When you learn something new

• Add to MEMORY.md under the right section.
• If it replaces an old fact, run memory-supersede.js.

Daily notes

• Create memory/YYYY-MM-DD.md with what happened.
• Bullet points. Decisions, contacts, technical details, anything worth keeping.

Dream Cycle

Agent-orchestrated consolidation. Run nightly or during quiet heartbeats.

1. Decay — node scripts/memory-decay.js
2. Review — Read recent memory/YYYY-MM-DD.md files
3. Integrate — Move significant items into MEMORY.md
4. Prune — Remove stale entries (low score, not structural)
5. Supersede — Chain any changed facts
6. Log — Append summary to memory/dream-log.md
7. Re-bootstrap — node scripts/memory-bootstrap.js (picks up new entries)

Full procedure with worked examples: references/dream-cycle.md. Cron job definitions: references/cron-templates.md.

Conversation Context Loading

When receiving a message from a group/topic, load context before responding:

1. Check archives/<channel>/<group>/summaries/topic-<id>.md for topic context
2. For cross-topic awareness, skim DIGEST.md
3. If summary seems stale, re-run archive + summarise for that group

This prevents the "I don't know what you're talking about" problem in long-running group conversations.

Limitations

• No semantic search. Recall matching is hash → substring → Jaccard word overlap.

Good for exact/close matches. Won't find conceptually related entries.

• Bootstrap hash is fragile. Based on first 20 chars — editing the start of

an entry creates a new hash and loses history.

• Dream cycles need judgment. The scripts provide mechanics; you provide

the editorial sense of what's worth keeping.

• Summarisation costs money. Uses LLM API calls. Free-tier models work

but quality varies. Configure summariseModel in archive-config.json.

• MEMORY.md is ground truth. Meta tracks metadata; Markdown is what you read.

Keep them in sync.

This is a work in progress. Start simple, observe what works, add complexity when the simple thing breaks.

Credentials & Privacy

Required credentials

Core memory scripts (4): No credentials needed. These are pure local file operations — read/write Markdown and JSON in your workspace.

Conversation summariser: Requires an LLM API key. Set one of:

• OPENROUTER_API_KEY in .env.openrouter or environment
• OPENAI_API_KEY in .env.openai or environment

The summariser sends conversation transcripts to the configured LLM provider for summarisation. This means your chat content is sent to a third-party API. Use a self-hosted model or review transcripts before summarising if this is a concern.

Conversation archiver: No credentials. Reads local OpenClaw session transcripts and writes local Markdown files.

What gets read

• MEMORY.md and memory/ files (your workspace)
• OpenClaw session transcripts (sessions.json + .jsonl files)
• .env.openrouter or .env.openai (for API keys, summariser only)
• archives/archive-config.json (optional config you create)

What gets written

• memory/memory-meta.json, memory/dream-log.md, memory/archive/
• archives/<channel>/<group>/ (raw transcripts, summaries, digests)

What gets sent externally

• Only conversation-summarise.js sends data externally (to your

configured LLM API for summarisation). All other scripts are fully local.

• Raw conversation text is sent to the LLM. If your transcripts contain

sensitive information, credentials, or private messages, those will be included unless you filter them first.