kjaylee/openclaw-mem

openclaw-mem

Local-first RAG memory system for AI agents. No API keys required — runs 100% offline with local embeddings.

Installation

pip install openclaw-mem
openclaw-mem init

This creates the workspace structure:

./memory/
├── core.md           # Key decisions & lessons learned
├── observations.md   # Structured observations
└── projects/         # Brain directories (per-project context)
.env                  # OPENCLAW_MEM_ROOT configuration

Key Commands

| Command | Description | |---------|-------------| | openclaw-mem search "query" | Semantic search over memory | | openclaw-mem index --all | Index all markdown files | | openclaw-mem index --changed | Incremental index (changed files only) | | openclaw-mem observe "text" --tag learning | Record a structured observation | | openclaw-mem auto-capture --since 6h | Extract observations from session transcripts | | openclaw-mem auto-capture --since 6h --route-to-brain | Auto-route observations to Brain files | | openclaw-mem brain-check | Check Brain files for injection patterns | | openclaw-mem brain-check --fix | Auto-fix injection patterns | | openclaw-mem archive --execute | Archive old memory (3-Layer: Hot/Warm/Cold) |

Brain Directories

Per-project persistent context stored in memory/projects/{name}.md:

# Create a project Brain
echo "# My Project Brain\n\n## Architecture\n- Stack: Python + FastAPI\n" > memory/projects/my-project.md

# Index it
openclaw-mem index memory/projects/my-project.md

# Search across all Brains
openclaw-mem search "project architecture"

# Verify integrity
openclaw-mem brain-check

Progressive Disclosure (2-Step Search)

Reduces token usage by returning summaries first, then full content on demand:

# Step 1: Get summaries (index view)
openclaw-mem search "deployment" --index
# Returns: chunk IDs + one-line summaries

# Step 2: Get full content for a specific chunk
openclaw-mem search --detail "chunk:0:abc123"
# Returns: full chunk text

Observation Tags

Tag observations for structured knowledge capture:

openclaw-mem observe "Redis cache TTL should be 1h" --tag decision
openclaw-mem observe "Always test with --dry-run first" --tag learning
openclaw-mem observe "Forgot to check edge case" --tag mistake
openclaw-mem observe "Service mesh pattern works well" --tag architecture
openclaw-mem observe "User prefers dark mode" --tag preference
openclaw-mem observe "Next: add WebSocket support" --tag next

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | OPENCLAW_MEM_ROOT | . | Workspace root directory | | OPENCLAW_MEM_DB_PATH | {root}/lance_db | LanceDB database path | | OPENCLAW_MEM_TABLE | memory | LanceDB table name | | OPENCLAW_MEM_BACKEND | local | Embedding backend: local, openai, ollama | | OPENCLAW_MEM_MODEL | all-MiniLM-L6-v2 | Embedding model name | | OPENCLAW_MEM_ARCHIVE_DIR | {root}/archive | Archive directory | | OPENCLAW_MEM_ARCHIVE_DAYS | 30 | Days before auto-archiving | | OPENCLAW_MEM_SESSION_DIR | {root}/sessions | Session transcripts directory |

Security

• Injection Defense: Brain files are scanned for prompt injection patterns
• Sanitizer: All indexed content passes through the injection sanitizer
• Local-first: No data leaves your machine — embeddings run locally