Persistent Memory
Adds persistent three-layer memory to any OpenClaw workspace. The agent gains semantic recall across sessions — decisions, facts, lessons, and institutional knowledge survive restarts.
Architecture
| Layer | Technology | Purpose |
|---|
| L1: Markdown | MEMORY.md + daily logs + reference/ | Human-readable curated knowledge |
| L2: Vector | ChromaDB + all-MiniLM-L6-v2 | Semantic search across all memories |
| L3: Graph | NetworkX | Relationship traversal between concepts |
All three layers sync together. The indexer updates L2 and L3 from L1 automatically.
⚠️ Critical Integration: OpenClaw Memory Configuration
Problem: OpenClaw has its own built-in memory search system, but by default it only indexes MEMORY.md and memory/*.md files. Critical workspace files like SOUL.md (agent directives), AGENTS.md (behavior rules), and PROJECTS.md (active work) are ignored.
Impact: Agents can violate explicit directives because they're not found in memory searches. This causes operational failures where agents ignore their own rules.
Solution: The configure_openclaw.py script adds a memorySearch configuration block to OpenClaw that indexes all critical workspace files. This makes directive compliance automatic rather than optional.
Setup
One command from workspace root:
bash skills/persistent-memory/scripts/unified_setup.sh
This automatically:
- ✅ Creates 3-layer memory system (Markdown + Vector + Graph)
- ✅ Installs all Python dependencies (ChromaDB, NetworkX, sentence-transformers)
- ✅ Configures OpenClaw memorySearch integration (directive compliance)
- ✅ Indexes existing MEMORY.md if present
- ✅ Sets up daily maintenance automation
No manual configuration needed. The script handles everything including OpenClaw integration that prevents agents from ignoring workspace directives (SOUL.md, AGENTS.md, etc.).
Daily Usage
Writing Memories
- MEMORY.md — Curated long-term knowledge (decisions, architecture, lessons learned). Update after significant events.
- memory/YYYY-MM-DD.md — Daily logs. Raw notes of what happened each day.
- reference/*.md — Institutional facts (people, repos, infrastructure, business rules). The agent's encyclopedia.
Indexing (after editing any memory file)
vector_memory/venv/bin/python vector_memory/indexer.py
The indexer parses MEMORY.md, reference/.md, and memory/.md into vector embeddings and rebuilds the knowledge graph. Run after every edit to keep layers in sync.
Searching
vector_memory/venv/bin/python vector_memory/search.py "your query"
Returns top-3 semantically similar chunks with source file and section.
Sync Status Check
vector_memory/venv/bin/python vector_memory/auto_retrieve.py --status
Reports sync health: MEMORY.md hash vs indexed state, chunk count, graph size. Use in heartbeats to detect drift.
Agent Behavior Rules
Add these to AGENTS.md or SOUL.md:
Pre-Response (mandatory)
Before answering questions about prior work, decisions, dates, people, or preferences — search memory first. Use memory_search or run auto_retrieve.py with the query. Never say "I don't remember" without checking.
CRITICAL: OpenClaw's built-in memory search should now automatically find directive files (SOUL.md, AGENTS.md) if configure_openclaw.py was run. If memory searches are not finding agent rules or workspace directives, the OpenClaw integration is missing or broken.
Pre-Action (mandatory)
Before executing any action that references an external identifier (URL, handle, email, repo name, address) — query reference/ files for the exact value. If not found, query vector memory. If still not found, ask the user. Never fabricate identifiers.
Post-Edit (mandatory)
After editing MEMORY.md or any file in reference/ or memory/ — re-index:
vector_memory/venv/bin/python vector_memory/indexer.py
Heartbeat Integration
Add to HEARTBEAT.md:
## Memory Sync Check
Run `vector_memory/venv/bin/python vector_memory/auto_retrieve.py --status` and if status is OUT_OF_SYNC, re-index with `vector_memory/venv/bin/python vector_memory/indexer.py`.
Reference Directory (Optional but Recommended)
Create reference/ in the workspace root as the agent's institutional knowledge base:
reference/
├── people.md — Contacts, roles, communication details
├── repos.md — GitHub repositories, URLs, status
├── infrastructure.md — Hosts, IPs, ports, services
├── business.md — Company info, strategies, rules
└── properties.md — Domain-specific entities (deals, products, etc.)
These files are vector-indexed alongside MEMORY.md. The agent queries them before any action involving external identifiers. Facts accumulate over time — the agent that never forgets.
File Structure After Setup
workspace/
├── MEMORY.md — Curated long-term memory (L1)
├── memory/
│ ├── 2026-02-17.md — Daily log
│ └── heartbeat-state.json — Sync tracking
├── reference/ — Institutional knowledge (optional)
│ ├── people.md
│ └── ...
└── vector_memory/
├── indexer.py — Index all markdown into vectors + graph
├── search.py — Semantic search CLI
├── graph.py — NetworkX knowledge graph
├── auto_retrieve.py — Status checker + auto-retrieval
├── chroma_db/ — Vector database (gitignored)
├── memory_graph.json — Knowledge graph (auto-generated)
└── venv/ — Python venv (gitignored)
Troubleshooting
- "No module named chromadb" — Run setup.sh again or activate the venv:
source vector_memory/venv/bin/activate
- OUT_OF_SYNC status — Run the indexer:
vector_memory/venv/bin/python vector_memory/indexer.py
- Empty search results — Check that MEMORY.md has content and the indexer has been run at least once
- SIGSEGV on indexing — Usually caused by incompatible ML libs. The setup script pins known-good versions.
- Agent ignoring SOUL.md/AGENTS.md directives — OpenClaw integration missing. Run
python skills/persistent-memory/scripts/configure_openclaw.py to fix.
- Memory searches not finding workspace files — Check OpenClaw configuration:
openclaw config get | grep memorySearch
- "Configuration verification failed" — Restart OpenClaw manually:
openclaw gateway restart
