A Markdown + JSON memory framework with conversation archiving for AI agents. Provides persistent long-term memory with biologically-inspired decay, recall b...
---
name: memory-dreaming
description: >
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.
source: https://github.com/ptburkis/openclaw-memory-dreaming
homepage: https://github.com/ptburkis/openclaw-memory-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
```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.
| 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
```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.
don't have the plugin yet? install it then click "run inline in claude" again.