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#

bash

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)#

bash

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:

json

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

Then archive and summarise:

bash

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.

FilePurposeMEMORY.mdLong-term memory (human-readable, agent-edited)memory/YYYY-MM-DD.mdDaily notes (raw session logs)memory/memory-meta.jsonDecay metadata per entrymemory/dream-log.mdDream cycle audit trailmemory/archive/YYYY-MM.mdArchived (forgotten) entries

Layer 2: Conversational Memory#

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

FilePurposearchives/<channel>/<group>/raw/Full conversation transcriptsarchives/<channel>/<group>/summaries/AI-generated topic summariesarchives/<channel>/<group>/DIGEST.mdCross-topic master digestarchives/<channel>/<group>/INDEX.mdTopic index with message counts

---

Memory Tiers#

TierAgeDecays?Noteshot<48hYesNew entrieswarm<30dYesRecentcold<365dYesLong-termarchived—Removedscore<0.1 + recalls<2crystallised∞Never20+ recalls

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

Decay Formula#

text

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#

ScriptPurposeWhen to runmemory-bootstrap.jsSeed meta from MEMORY.mdSetup + after adding entriesmemory-decay.jsRecalculate scores, tier transitionsStart of dream cyclememory-recall-logger.jsLog recall events, boost scoresAfter every memory searchmemory-supersede.jsCreate temporal fact chainsWhen facts change

Conversation Memory#

ScriptPurposeWhen to runconversation-archive.jsArchive channel transcriptsNightly (before summarise)conversation-summarise.jsAI-summarise topics + digestNightly (after archive)

Usage Examples#

bash

# 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: bash

   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.