Skip to content
BASS

Memory System

Memory System

Section titled “Memory System”

Principle: Disk is Source of Truth

Section titled “Principle: Disk is Source of Truth”

All agent knowledge lives on disk. Write outcomes to files immediately. Memory in context is ephemeral — disk is canonical.

Directory Structure

Section titled “Directory Structure”
/home/winnie/.openclaw/workspace/
├── MEMORY.md           # Long-term curated essentials (agent reads on startup)
├── HANDOVER.md         # Machine-readable session handover (overwritten each session)
├── HEARTBEAT.md        # Current Now/Next/Blockers (updated each heartbeat)
├── AGENTS.md           # Delegation + spawning rules
├── IDENTITY.md         # Winnie's identity and role
├── SOUL.md             # Core operating principles + checkpoint protocol
├── memory/
│   ├── daily/          # Append-only session logs (YYYY-MM-DD.md)
│   ├── decisions/      # CEO/Winnie decisions by month (YYYY-MM.md)
│   ├── projects/       # Per-project status files
│   ├── ops/            # Operational reference docs
│   ├── research/       # Research outputs by topic
│   └── checkpoints/    # Sub-agent result files (subagent-<label>.md)

File Types

Section titled “File Types”

Ephemeral (session-scoped)

Section titled “Ephemeral (session-scoped)”
  • HANDOVER.md — Overwritten on every checkpoint. Contains: Last Action, System State, Scope Rules, Dev Model, Next Actions.
  • HEARTBEAT.md — Updated every 30 minutes. Contains: Now, Next, Blockers.

Append-Only

Section titled “Append-Only”
  • memory/daily/YYYY-MM-DD.md — Session summaries. Never modify past entries.

Canonical Reference

Section titled “Canonical Reference”
  • MEMORY.md — Curated essentials. Updated when stable patterns are confirmed.
  • AGENTS.md — Delegation rules, routing, agent fleet table.
  • memory/ops/*.md — Operational procedures, model catalog, corrections log.
  • memory/projects/*.md — Per-project status.
  • memory/decisions/YYYY-MM.md — Decision log by month.

Memory Protocol

Section titled “Memory Protocol”

On session startup, agents read:

  1. HANDOVER.md (last session state)
  2. MEMORY.md (curated long-term memory)
  3. HEARTBEAT.md (current status)
  4. Project-specific files (FRANKEL.md, etc.)

On session end (checkpoint), agents write:

  1. HANDOVER.md (current state)
  2. memory/daily/YYYY-MM-DD.md (append session summary)
  3. HEARTBEAT.md (update Now/Next/Blockers)
  4. Any project or ops updates

After Every Outcome

Section titled “After Every Outcome”
  • Summary → memory/projects/<PROJECT>.md
  • Append → memory/daily/YYYY-MM-DD.md
  • Config/routing changed → memory/ops/CHANGELOG.md
  • CEO decision → memory/decisions/YYYY-MM.md

QMD Vector Backend

Section titled “QMD Vector Backend”
  • Engine: QMD 1.0.7 (Bun 1.3.9)
  • Purpose: Session transcript indexing for semantic search via memory_search
  • Retention: 30 days
  • Indexing: 29 files, 112 vectors at setup
  • CPU-only: Models ~2GB, unloaded after idle
  • Use memory_search for deep lookups across transcript history

Key Files Reference

Section titled “Key Files Reference”
FileWhen to ReadWhen to Write
MEMORY.mdCold start, session resetWhen stable patterns confirmed
HANDOVER.mdSession startEvery checkpoint
HEARTBEAT.mdHeartbeat runEvery heartbeat
AGENTS.mdWhen routing/spawningAfter routing changes
memory/ops/corrections.mdBefore starting workWhen new mistake logged
memory/ops/CHANGELOG.mdWhen checking config historyAfter config changes
memory/decisions/YYYY-MM.mdWhen need decision contextAfter CEO decisions

Search Strategy

Section titled “Search Strategy”
  1. MEMORY.md — Start here. Curated one-liners with pointers.
  2. Topic files (memory/ops/*.md, memory/projects/*.md) — Detail reference.
  3. memory_search — Semantic search across transcript history (last resort — slow).
  4. memory/daily/YYYY-MM-DD.md — Chronological session logs (last resort — large files).

See Also

Section titled “See Also”