docker pull ghcr.io/encreor/rlm-claude

Then configure Claude Code to use the Docker container (see Docker setup below).
Restart Claude Code. Done.
Upgrading from v0.9.0 or earlier
v0.9.1 moved the source code from mcp_server/ to src/mcp_server/ (PyPA best practice). A compatibility symlink is included so existing installations keep working, but we recommend re-running the installer:

bash
cd rlm-claude
git pull
./install.sh # reconfigures the MCP server path

Your data (~/.claude/rlm/) is untouched. Only the server path is updated.

---
How It Works

┌─────────────────────────┐
│ Claude Code CLI │
└────────────┬────────────┘
│
┌────────────▼────────────┐
│ RLM MCP Server │
│ (14 tools) │
└────────────┬────────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
┌─────────▼────────┐ ┌──────▼──────┐ ┌──────────▼─────────┐
│ Insights │ │ Chunks │ │ Retention │
│ (key decisions, │ │ (full conv │ │ (auto-archive, │
│ facts, prefs) │ │ history) │ │ restore, purge) │
└──────────────────┘ └─────────────┘ └────────────────────┘

Auto-Save Before Context Loss

RLM hooks into Claude Code's /compact event. Before your context is wiped, RLM automatically saves a snapshot. No action needed.
Two Memory Systems
| System | What it stores | How to use |

|--------|---------------|------------|

| Insights | Key decisions, facts, preferences | rlm_remember() / rlm_recall() |

| Chunks | Full conversation segments | rlm_chunk() / rlm_peek() / rlm_grep() |
---
Features
Memory & Insights
- rlm_remember - Save decisions, facts, preferences with categories and importance levels
- rlm_recall - Search insights by keyword (multi-word tokenized), category, or importance
- rlm_forget - Remove an insight
- rlm_status - System overview (insight count, chunk stats, access metrics)
Conversation History
- rlm_chunk - Save conversation segments with typed categorization (snapshot, session, debug; insight redirects to rlm_remember)
- rlm_peek - Read a chunk (full or partial by line range)
- rlm_grep - Regex search across all chunks (+ fuzzy matching for typo tolerance)
- rlm_search - Hybrid search: BM25 + semantic cosine similarity (FR/EN, accent-normalized, chunks + insights)
- rlm_list_chunks - List all chunks with metadata
Multi-Project Organization
- rlm_sessions - Browse sessions by project or domain
- rlm_domains - List available domains for categorization
- Auto-detection of project from git or working directory
- Cross-project filtering on all search tools
Smart Retention
- rlm_retention_preview - Preview what would be archived (dry-run)
- rlm_retention_run - Archive old unused chunks, purge ancient ones
- rlm_restore - Bring back archived chunks
- 3-zone lifecycle: Active → Archive (.gz) → Purge
- Immunity system: critical tags, frequent access, and keywords protect chunks
Auto-Chunking & Memory Routing (Hooks)
- PreCompact hook: Automatic snapshot before /compact or auto-compact
- PostToolUse hook (rlm_chunk): Stats tracking after chunk operations
- PostToolUse hook (Write/Edit): Detects writes to Claude Code's auto-memory and nudges toward RLM for decisions, insights, and session logs
- User-driven philosophy: you decide when to chunk, the system saves before loss
Semantic Search (optional)
- Hybrid BM25 + cosine - Combines keyword matching with vector similarity for better relevance
- Auto-embedding - New chunks are automatically embedded at creation time
- Two providers - Model2Vec (fast, 256d) or FastEmbed (accurate, 384d)
- Graceful degradation - Falls back to pure BM25 when semantic deps are not installed
Provider comparison (benchmark on 108 chunks)
| | Model2Vec (default) | FastEmbed |

|---|---|---|

| Model | potion-multilingual-128M | paraphrase-multilingual-MiniLM-L12-v2 |

| Dimensions | 256 | 384 |

| Embed 108 chunks | 0.06s | 1.30s |

| Search latency | 0.1ms/query | 1.5ms/query |

| Memory | 0.1 MB | 0.3 MB |

| Disk (model) | ~35 MB | ~230 MB |

| Semantic quality | Good (keyword-biased) | Better (true semantic) |

| Speed | 21x faster | Baseline |
Top-5 result overlap between providers: ~1.6/5 (different results in 7/8 queries). FastEmbed captures more semantic meaning while Model2Vec leans toward keyword similarity. The hybrid BM25 + cosine fusion compensates for both weaknesses.
Recommendation: Start with Model2Vec (default). Switch to FastEmbed only if you need better semantic accuracy and can afford the slower startup.

bash