Skill: ptburkis/openclaw-memory-dreaming (version 0.1.2)

--- 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.


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)