| name | observational-memory |
| description | Two-tier compressed memory system using Observer and Reflector background agents. Replaces raw conversation history with dense, prioritized observations and long-term reflections.
|
Observational Memory — Skill Guide
Overview
Two background agents maintain compressed memory files that your main agent reads on startup:
memory/observations.md — Timestamped, prioritized notes from recent conversations (updated every 15 min)memory/reflections.md — Condensed long-term memory: identity, projects, preferences (updated daily)
Installation
git clone https://github.com/intertwine/observational-memory.git
cd observational-memory
bash scripts/install.sh
Or manually: copy the prompts from reference/ into your skills directory and create cron jobs per the instructions below.
AGENTS.md Integration
Add to your "Every Session" context loading:
## Every Session
...
5. Read `memory/observations.md` — recent compressed observations (auto-maintained by Observer)
6. Read `memory/reflections.md` — long-term condensed memory (auto-maintained by Reflector)
Cron Jobs
The install script creates two cron jobs:
| Job | Schedule | Prompt | Purpose |
|---|
observer-memory | */15 * * * * | observer-prompt.md | Compress recent messages → observations |
reflector-memory | 0 4 * * * | reflector-prompt.md | Incrementally update reflections from new observations |
Configuration
Model
Default: anthropic/claude-sonnet-4-20250514. Override during install:
bash scripts/install.sh --model anthropic/claude-opus-4-6
Frequency
- Observer:
--observer-interval "*/30 * * * *" (default: every 15 min)
- Reflector:
--reflector-schedule "0 6 * * *" (default: daily at 04:00 UTC)
Manual Triggers
openclaw cron trigger observer-memory
openclaw cron trigger reflector-memory
Tuning
- Observer threshold: Skips runs with fewer than ~10 new messages (configurable in prompt)
- Reflector target: Aims for 200–600 lines in reflections.md (configurable in prompt)
- Reflector incremental: Only processes observations since
Last reflected timestamp; chunks large inputs automatically
- Observation retention: 7 days before the reflector trims old entries
Edit the prompts in reference/ to adjust priority definitions, compression rules, or output format.
Enhanced Search with QMD (Optional)
QMD adds hybrid search (BM25 + vectors + reranking) over your compressed memory files, making it easy to recall specific observations from weeks or months ago.
bash scripts/enable-qmd.sh
bash scripts/enable-qmd.sh --disable
QMD is optional — OM works great standalone. If QMD is unavailable, OpenClaw falls back to built-in vector search. See the README section on QMD for architecture details and resource requirements.
Relationship to MEMORY.md
Options:
- Replace MEMORY.md — let observations + reflections be your entire memory system
- Supplement — keep MEMORY.md for manually curated notes alongside auto-generated memory
Option 1 is recommended for most setups.
