context-memory

name

context-memory

description

Multi-threaded conversation memory organized by topic instead of by date. Enables seamless context switching, compaction resilience, and sub-agent tracking — all file-based, no code changes to OpenClaw. Use when you want your agent to maintain separate conversation threads per project/topic, survive context compaction without losing the thread, track sub-agent spawns with model/task/duration, and output a structured conversation-map.json for visualization clients.

Context Memory

Organize conversation memory by topic rather than by date. Each subject gets its own folder with a conversation thread, status summary, and artifacts. A master timeline tracks all context switches, compaction events, and sub-agent spawns.

Setup

Run the bootstrap script to create the directory structure:

bash scripts/bootstrap.sh

Then add the context memory instructions to your AGENTS.md (see below).

Directory Structure

memory/
├── CONTEXT_LOG.md           # Master timeline (reverse chronological)
├── conversation-map.json    # Structured event graph for client apps
├── contexts/
│   ├── <topic-name>/
│   │   ├── THREAD.md        # Curated conversation excerpts
│   │   ├── STATUS.md        # Current state (<1KB, always fresh)
│   │   └── artifacts/       # Work products
│   └── ...
├── YYYY-MM-DD.md            # Daily logs (unchanged, still works)
└── session-state.md         # Compact recovery (enhanced with active context)

AGENTS.md Instructions

Add this section to your AGENTS.md under Memory:

Context Detection

Every message belongs to a context. Determine which:

• Explicit: "Let's talk about the job search" → job-search
• Implicit: "Any updates from Paradigm?" → job-search
• New topic: create new context folder with mkdir -p memory/contexts/<name>/artifacts
• Ambiguous: ask briefly — "Is this about [X] or something new?"

Context IDs

Every context switch gets a unique ID: ctx-{DD}-{seq} (e.g. ctx-08-001). Sub-agents inherit their parent: ctx-08-001-a1. Sequence resets daily.

On Every Message

1. Determine the context (detect or continue current)
2. If context changed: read memory/contexts/<new>/STATUS.md, log switch to memory/CONTEXT_LOG.md
3. After responding: append relevant exchange to THREAD.md, update STATUS.md if state changed
4. Update memory/conversation-map.json with any new events

On Session Start / After Compaction

1. Read memory/CONTEXT_LOG.md (last ~30 entries) — understand what's been happening
2. Read memory/session-state.md if exists — compact recovery
3. Read the STATUS.md of the most recent context — resume where left off

On Spawning Sub-Agents

Log to both CONTEXT_LOG.md and conversation-map.json:

• Agent ID (ctx-XX-NNN-aN), model used, task description, parent context
• On completion: add duration, result summary, artifacts created

On Compaction

1. Write memory/session-state.md with current active context name
2. Ensure current context's THREAD.md and STATUS.md are up to date
3. Log [COMPACTION] to CONTEXT_LOG.md with list of active contexts

Naming Conventions

• Lowercase, hyphenated: job-search, project-voxbench, htmx-4
• Prefix for clarity: project- for code, client- for client work, biz- for business
• No prefix for general topics

Maintenance (During Heartbeats)

• Contexts untouched >7 days → mark as dormant in conversation-map.json
• THREAD.md >200 lines → archive older entries to THREAD_ARCHIVE.md
• CONTEXT_LOG.md >200 lines → archive to CONTEXT_LOG_ARCHIVE.md

File Formats

CONTEXT_LOG.md

# Context Log

## 2026-02-08

### 05:31 — [CONTEXT: openclaw-memory-design] triggered by: user message
- Designed file-based memory system for OpenClaw
- Created Notion design doc
  - ctx-08-001-a1: Sonnet, 3m42s, wrote Notion page

### 00:00 — [COMPACTION]
- Active contexts at compaction: project-voxbench, stukennedy-com

STATUS.md (per context)

# Job Search — Status
**Last Updated:** 2026-02-07 18:00

## Active
- **Paradigm Talent** — Staff SWE, £140-220k, remote UK
  - Status: CV sent, awaiting response

## Next Actions
- [ ] Follow up if no response by Feb 10

THREAD.md (per context)

# Job Search Thread
## Active Since: 2026-02-06

### Latest (2026-02-07)
**User:** Any updates on the Paradigm role?
**Agent:** Anthony McCabe received your LinkedIn message. No response yet.

### Earlier Context
- SwitchUp: €120K max, gap too large

conversation-map.json

{
  "version": 1,
  "contexts": {
    "<name>": { "name": "Display Name", "color": "#hex", "created": "ISO", "lastActive": "ISO", "status": "active|dormant" }
  },
  "events": [
    { "id": "ctx-08-001", "type": "context_switch", "context": "<name>", "trigger": "user_message", "timestamp": "ISO", "summary": "..." },
    { "id": "ctx-08-001-a1", "type": "agent_spawn", "parentId": "ctx-08-001", "model": "...", "task": "...", "durationMs": 0, "result": "ok", "artifacts": [] },
    { "id": "ctx-07-015", "type": "compaction", "timestamp": "ISO", "activeContexts": ["project-x", "job-search"] }
  ]
}

Integration

• Daily logs (memory/YYYY-MM-DD.md): Unchanged — still works for raw chronological record
• MEMORY.md: Unchanged — still for curated long-term facts
• Vector search (memory_search): Automatically indexes new files in memory/contexts/
• ClawClient: Optional visualization app that reads conversation-map.json (github.com/stukennedy/clawclient)

Token Efficiency

• STATUS.md files are <1KB each — cheap to load on context switch
• Only the active context's files are read, not all contexts
• THREAD.md read on-demand, not at startup
• CONTEXT_LOG.md is a lightweight index (~200 lines max)
• No new tools or API calls — just file reads/writes the model already does