Memory Dreaming

A Markdown + JSON memory framework with conversation archiving for AI agents. Provides persistent long-term memory with biologically-inspired decay, recall boosting, temporal fact chains, dream-cycle consolidation, and channel-agnostic conversation archiving with AI-generated summaries. No vector database, graph store, or external service required. Use when you need: agent memory that persists across sessions, conversation context across channels/groups/topics, fact lifecycle tracking (supersession), or automated memory maintenance via dream cycles.

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.

File	Purpose
MEMORY.md	Long-term memory (human-readable, agent-edited)
memory/YYYY-MM-DD.md	Daily notes (raw session logs)
memory/memory-meta.json	Decay metadata per entry
memory/dream-log.md	Dream cycle audit trail
memory/archive/YYYY-MM.md	Archived (forgotten) entries

Layer 2: Conversational Memory

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

File	Purpose
archives/<channel>/<group>/raw/	Full conversation transcripts
archives/<channel>/<group>/summaries/	AI-generated topic summaries
archives/<channel>/<group>/DIGEST.md	Cross-topic master digest
archives/<channel>/<group>/INDEX.md	Topic index with message counts

---

Memory Tiers

Tier	Age	Decays?	Notes
hot	<48h	Yes	New entries
warm	<30d	Yes	Recent
cold	<365d	Yes	Long-term
archived	—	Removed	score<0.1 + recalls<2
crystallised	∞	Never	20+ recalls

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

Script	Purpose	When to run
memory-bootstrap.js	Seed meta from MEMORY.md	Setup + after adding entries
memory-decay.js	Recalculate scores, tier transitions	Start of dream cycle
memory-recall-logger.js	Log recall events, boost scores	After every memory search
memory-supersede.js	Create temporal fact chains	When facts change

Conversation Memory

Script	Purpose	When to run
conversation-archive.js	Archive channel transcripts	Nightly (before summarise)
conversation-summarise.js	AI-summarise topics + digest	Nightly (after archive)

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.