ClawHub

Tiered Memory

Prompts

Two-tier memory system for OpenClaw agents. Tier 0 = QMD semantic search for recent memories (7-14 days). Tier 1 = SQLite archive for long-term storage. Auto-archives old sessions with LLM summarization. Use when building agents that need efficient, scalable memory management.

Install

openclaw skills install agent-tiered-memory

Tiered Memory Skill

Two-tier memory system combining OpenClaw's QMD semantic search with SQLite archival. Keeps recent memories fast and searchable while compressing old sessions for long-term storage.

Architecture

┌─────────────────────────────────────────┐
│  TIER 0: QMD Semantic Search            │
│  ├── Hot memory (7-14 days)             │
│  ├── GPU-accelerated vector search      │
│  └── Searches: MEMORY.md, memory/*.md   │
├─────────────────────────────────────────┤
│  TIER 1: SQLite Archive                 │
│  ├── Cold storage (14+ days)            │
│  ├── Compressed summaries + key facts   │
│  └── Structured queries via SQL         │
└─────────────────────────────────────────┘

Quick Start

1. Ensure QMD is Enabled

QMD comes with OpenClaw. Check status:

openclaw doctor

Should show QMD as available. If not, check ~/.openclaw/openclaw.json:

{
  "memory": {
    "qmd": {
      "enabled": true,
      "device": "cuda"
    }
  }
}

2. Set Up Archive Directory

mkdir -p ~/.openclaw/workspace/memory/archive

3. Install Cron Job (Auto-archive)

# Add to crontab
crontab -e

# Add this line for daily 2 AM archive
0 2 * * * /usr/bin/python3 ~/.openclaw/skills/tiered-memory/scripts/memory_archiver.py --days 14 >> ~/.openclaw/workspace/memory/archive.log 2>&1

4. Use in Your Agent

import sys
sys.path.insert(0, '~/.openclaw/skills/tiered-memory/scripts')
from tiered_memory import TieredMemory

mem = TieredMemory()

# Query across both tiers
results = mem.search("AgentBear project")

Manual Archive

# See what would be archived
python3 ~/.openclaw/skills/tiered-memory/scripts/memory_archiver.py --dry-run

# Archive files older than 14 days
python3 ~/.openclaw/skills/tiered-memory/scripts/memory_archiver.py

# Archive with custom threshold
python3 ~/.openclaw/skills/tiered-memory/scripts/memory_archiver.py --days 7

# Skip LLM (faster, basic summaries)
python3 ~/.openclaw/skills/tiered-memory/scripts/memory_archiver.py --skip-llm

Query Archives

# List all archived sessions
python3 ~/.openclaw/skills/tiered-memory/scripts/memory_archiver.py --list

# Search archived summaries
python3 ~/.openclaw/skills/tiered-memory/scripts/memory_archiver.py --search "AgentBear"

How It Works

Daily Flow

  1. During Day: Agent writes to memory/YYYY-MM-DD.md
  2. QMD Indexes: Real-time semantic indexing
  3. At 2 AM: Cron runs archiver
  4. Old Files: Summarized → SQLite → moved to archive/

Search Priority

When an agent searches memory:

  1. QMD search (Tier 0) - semantic, fuzzy, fast
  2. If not found or need history: Query SQLite (Tier 1)

Archive Format

FieldTypeDescription
session_dateDATEOriginal file date
summaryTEXTLLM-generated summary
key_factsJSONImportant facts extracted
topicsJSONTags/categories
message_countINTLines in original file

Database Schema

CREATE TABLE archived_sessions (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    source_file TEXT NOT NULL,
    session_date DATE NOT NULL,
    summary TEXT NOT NULL,
    key_facts TEXT,  -- JSON array
    topics TEXT,     -- JSON array
    message_count INTEGER,
    archived_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_date ON archived_sessions(session_date);
CREATE INDEX idx_topics ON archived_sessions(topics);

Scripts

  • scripts/memory_archiver.py - Archive old files to SQLite
  • scripts/tiered_memory.py - Unified search across both tiers

Files

  • references/qmd-setup.md - QMD configuration details
  • references/archiver-api.md - Archiver script API reference

Notes

  • QMD requires CUDA GPU for best performance (falls back to CPU)
  • Archive uses Ollama for summarization (qwen2.5-coder:14b default)
  • Original files are preserved in archive/ folder
  • SQLite DB at ~/.openclaw/memory_archive.db

Troubleshooting

QMD not working? See references/qmd-setup.md

Archive failing? Check Ollama is running: ollama list

Want to restore archived file? Just move it back from memory/archive/ to memory/

More in Prompts