Reclaw Memory System

Reclaw is an append-only event log that replaces daily memory files. It assumes the current OpenClaw environment already has the Reclaw plugin installed. All memory lives in log.jsonl as structured entries. Extraction happens automatically at session end — you don't write to the log directly. Your job is to state information clearly in conversation so the extraction hook captures it.

How Memory Works

1. MEMORY.md is auto-loaded into every session. It has a manual section (goals, preferences) and a generated Reclaw memory snapshot updated nightly.
2. Reclaw session summary is written into MEMORY.md after each session extraction.
3. Subject markdown projections are generated under ~/.openclaw/reclaw/memory/ so OpenClaw can semantically index event-log content through its builtin markdown memory path.
4. memory_search finds entries by keyword, type, subject, or status when the Reclaw plugin has registered that tool in the current OpenClaw environment, and can hit semantic results from MEMORY.md plus generated subject projections.
5. memory_get retrieves a specific entry by ID, reads MEMORY.md, or fetches a full session transcript when the Reclaw plugin has registered that tool in the current OpenClaw environment.

Start with what's already in context (steps 1-3). Only call tools when you need something specific.

Entry Types

Subjects

Every non-session_summary entry has a subject — a kebab-case slug like auth-migration or reclaw. Subjects are tracked in a registry with a type: project, person, system, or topic (default).

When discussing something new, use a clear kebab-case slug. The extraction hook auto-creates subjects it hasn't seen. To explicitly manage subjects:

# List all subjects
openclaw reclaw subjects list

# Add a subject with a type
openclaw reclaw subjects add auth-migration --type project
openclaw reclaw subjects add alice-chen --type person

# Rename a subject (updates registry and all log entries)
openclaw reclaw subjects rename old-slug new-slug

Using memory_search

Combines structured log filters with keyword search and semantic search over MEMORY.md plus generated subject projections.

# Keyword search
memory_search({"query": "webhook retries"})

# Structured filters
memory_search({"type": "decision", "subject": "auth-migration"})
memory_search({"type": "task", "status": "open"})
memory_search({"type": "question"})

# Combined
memory_search({"query": "backoff", "type": "fact", "subject": "auth-migration"})

At least one of query, type, subject, or status is required.

Markdown Projections

Reclaw keeps one generated markdown file per subject under ~/.openclaw/reclaw/memory/. These files are derived from log.jsonl and exist so OpenClaw's builtin markdown indexer can semantically search event-log content.

• Treat projection files as generated output — don't manually edit them
• Successful live extraction refreshes touched subject projections automatically
• Successful non-dry-run imports refresh the full projection set automatically
• If the index seems stale, rebuild with openclaw reclaw projection refresh

Using memory_get

Three lookup modes based on the path value:

# By entry ID (12-char nanoid from search results)
memory_get({"path": "r7Wp3nKx_mZe"})

# By session transcript (from an entry's session field)
memory_get({"path": "session:abc123def456"})

# By file path
memory_get({"path": "MEMORY.md"})

Reading an entry by ID increments its usage score, which helps it persist in the nightly memory snapshot.

Citations

When referencing a prior event in conversation, cite it as [<12-char-id>] (e.g., [r7Wp3nKx_mZe]). This format is tracked for usage scoring — cited entries are more likely to appear in future memory snapshots.

Corrections and Updates

The log is append-only. To correct something:

• State the correction clearly in conversation. Extraction writes a new entry on the same subject.
• To mark a task done, say so explicitly. Extraction emits a new task entry with status: "done".
• To answer a question, discuss the resolution. Extraction captures the answer as a fact or decision.

Old entries are never modified. Current state is reconstructed by reading a subject's entries chronologically.

Hard Filter

Only user-specific information belongs in the log. Ask: "Would I need to know this person to know this?" If a general-purpose LLM could produce the content without user context, it should not be extracted. No generic knowledge, no dependency lists, no boilerplate.

CLI Commands

# Recent log entries
openclaw reclaw log
openclaw reclaw log --type decision --subject auth-migration --limit 10

# Search with filters
openclaw reclaw search "webhook"
openclaw reclaw search --type task --status open
openclaw reclaw search --subject auth-migration --from 2026-02-01 --to 2026-03-01

# Trace a subject's chronological history
openclaw reclaw trace
openclaw reclaw trace --subject auth-migration
openclaw reclaw trace <entry-id>

# Subject management
openclaw reclaw subjects list
openclaw reclaw subjects add <slug> --type <project|person|system|topic>
openclaw reclaw subjects rename <old-slug> <new-slug>

# Refresh generated subject markdown projections
openclaw reclaw projection refresh
openclaw reclaw projection list

# Regenerate the MEMORY.md memory snapshot now
openclaw reclaw snapshot refresh

# Force-refresh MEMORY.md session summary block from log
openclaw reclaw summary refresh

# Import historical conversations
openclaw reclaw import <chatgpt|claude|grok|openclaw> <file>
openclaw reclaw import status
openclaw reclaw import resume <jobId>

# Setup
openclaw reclaw init
openclaw reclaw verify
openclaw reclaw uninstall