Roampal Core is an MCP server that gives AI coding assistants (Claude Code, OpenCode) persistent, outcome-based memory across sessions — automatically injecting relevant context and learning from exchange outcomes. All data is stored locally and privately.
MCP Tools:
search_memory: Query across all memory collections (working, history, patterns, memory_bank, books) for relevant context.add_to_memory_bank: Permanently store user identity, preferences, and goals.update_memory: Correct or update an existing memory entry by ID.delete_memory: Remove outdated or incorrect memories by ID.score_memories: Score exchange outcomes so good advice is promoted and bad advice demoted (Claude Code uses the main LLM; OpenCode uses an independent sidecar model).record_response: Store key takeaways from significant exchanges to build historical and pattern memory over time.
Key Features:
Automatic context injection before the AI sees user messages — no manual calls needed.
Five memory collections with varying lifespans: working (24h), history (30d), patterns (persistent), memory_bank (permanent), books (permanent).
Document ingestion for permanent reference storage in the books collection.
Auto-detection of platform (Claude Code hooks / OpenCode plugin), self-healing server restarts, and CLI tools for configuration, diagnostics, and statistics.
Integrates with local models via Ollama to perform sidecar scoring of AI exchanges, allowing for private and independent evaluation of memory performance.
Roampal — Outcome-Based Persistent Memory MCP Server
Why?
AI coding assistants forget everything between sessions. You explain your architecture, your preferences, your conventions — again. When they give bad advice, there's no mechanism to learn from it.
Roampal is an MCP server that gives your AI persistent, outcome-based memory across every session. Good advice gets promoted. Bad advice gets demoted. Your AI learns what works and what doesn't — automatically, with zero workflow changes.
Quick Start
pip install roampal
roampal initAuto-detects installed tools. Restart your editor and start chatting.
Target a specific tool:
roampal init --claude-codeorroampal init --opencode
The core loop is identical — both platforms inject context, capture exchanges, and score outcomes. The delivery mechanism differs:
Claude Code | OpenCode | |
Context injection | Hooks (stdout) | Plugin (system prompt) |
Exchange capture | Stop hook | Plugin |
Scoring | Main LLM via | Independent sidecar (your chosen model > Zen free) |
Self-healing | Hooks auto-restart server on failure | Plugin auto-restarts server on failure |
Claude Code prompts the main LLM to score each exchange via the score_memories tool. OpenCode never self-scores — an independent sidecar (a separate API call) reviews each exchange as a third party, removing self-assessment bias. The score_memories tool is not registered on OpenCode. During roampal init or roampal sidecar setup, Roampal detects local models (Ollama, LM Studio, etc.) and lets you choose a scoring model. If configured, these take priority (Zen is skipped for privacy). A cheap or local model works great — scoring doesn't need a powerful model. Defaults to Zen free models (remote, best-effort) if you skip setup.
How It Works
When you type a message, Roampal automatically injects relevant context before your AI sees it:
You type:
fix the auth bugYour AI sees:
═══ KNOWN CONTEXT ═══
• JWT refresh pattern fixed auth loop [id:patterns_a1b2] (3d, 90% proven, patterns)
• User prefers: never stage git changes [id:mb_c3d4] (memory_bank)
═══ END CONTEXT ═══
fix the auth bugNo manual calls. No workflow changes. It just works.
The Loop
You type a message
Roampal injects relevant context automatically (hooks in Claude Code, plugin in OpenCode)
AI responds with full awareness of your history, preferences, and what worked before
Outcome scored — good advice gets promoted, bad advice gets demoted
Repeat — the system gets smarter every exchange
Five Memory Collections
Collection | Purpose | Lifetime |
| Current session context | 24h — promotes if useful, deleted otherwise |
| Past conversations | 30 days, outcome-scored |
| Proven solutions | Persistent while useful, promoted from history |
| Identity, preferences, goals | Permanent |
| Uploaded reference docs | Permanent |
Commands
roampal init # Auto-detect and configure installed tools
roampal init --claude-code # Configure Claude Code explicitly
roampal init --opencode # Configure OpenCode explicitly
roampal init --no-input # Non-interactive setup (CI/scripts)
roampal start # Start the HTTP server manually
roampal stop # Stop the HTTP server
roampal status # Check if server is running
roampal status --json # Machine-readable status (for scripting)
roampal stats # View memory statistics
roampal stats --json # Machine-readable statistics (for scripting)
roampal doctor # Diagnose installation issues
roampal summarize # Summarize long memories (retroactive cleanup)
roampal score # Score the last exchange (manual/testing)
roampal context # Output recent exchange context
roampal ingest <file> # Add documents to books collection
roampal books # List all ingested books
roampal remove <title> # Remove a book by title
roampal sidecar status # Check scoring model configuration (OpenCode)
roampal sidecar setup # Configure scoring model (OpenCode)
roampal sidecar disable # Remove scoring model configuration (OpenCode)MCP Tools
Your AI gets these memory tools:
Tool | Description | Platforms |
| Deep search across all collections | Both |
| Store permanent facts (identity, preferences, goals) | Both |
| Correct or update existing memories | Both |
| Remove outdated info | Both |
| Score previous exchange outcomes | Claude Code |
| Store key takeaways from significant exchanges | Both |
How scoring works: Claude Code's hooks prompt the main LLM to call
score_memoriesevery turn. OpenCode uses an independent sidecar that scores silently in the background — the model never sees a scoring prompt andscore_memoriesis not registered as a tool. If the sidecar is unavailable, a warning prompts the user to runroampal sidecar setup. Choose your scoring model duringroampal initor viaroampal sidecar setup.
What's Different?
Without Roampal | With Roampal |
Forgets everything between sessions | Remembers you, your preferences, what worked |
You repeat context every time | Context injected automatically |
No learning from mistakes | Outcomes tracked — bad advice gets demoted |
No document memory | Ingest docs, searchable forever |
Benchmarks
Tested across 10 adversarial scenarios designed to trick similarity search (200 total tests):
Condition | Top-1 Accuracy |
RAG baseline (vector search only) | 10% |
+ Cross-encoder reranking | 20% |
Full Roampal (outcomes + reranking) | 10% → 60% at maturity |
Outcome learning provides a 5x improvement over reranking alone (+50 pts vs +10 pts). Roampal vs plain vector DB: 40% vs 0% accuracy on adversarial queries (p=0.000135).
Full benchmark data: dev/benchmarks/results/
How Roampal Compares
Feature | Roampal Core | .cursorrules / CLAUDE.md | Mem0 |
Learns from outcomes | Yes — bad advice demoted, good advice promoted | No | No |
Zero-config context injection | Yes — injected automatically (hooks or plugin) | Manual file editing | API calls required |
Works across sessions | Yes — 5 memory collections with promotion | Per-project static files | Yes |
Fully local / private | Yes — all data on your machine | Yes | Cloud or self-hosted |
Open source | Apache 2.0 | N/A | Apache 2.0 |
┌─────────────────────────────────────────────────────────┐
│ pip install roampal && roampal init │
│ Claude Code: hooks + MCP → ~/.claude/ │
│ OpenCode: plugin + MCP → ~/.config/opencode/ │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ HTTP Hook Server (port 27182) │
│ Auto-started on first use, self-heals on failure │
│ Manual control: roampal start / roampal stop │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ User types message │
│ → Hook/plugin calls HTTP server for context │
│ → AI sees relevant memories, responds │
│ → Exchange stored, scored (hooks or sidecar) │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ Single-Writer Backend │
│ FastAPI → UnifiedMemorySystem → ChromaDB │
│ All clients share one server, isolated by session │
└─────────────────────────────────────────────────────────┘See dev/docs/ for full technical details.
Requirements
Python 3.10+
One of: Claude Code or OpenCode
Platforms: Windows, macOS, Linux (primarily developed and tested on Windows)
Troubleshooting
Restart Claude Code (hooks load on startup)
Check HTTP server:
curl http://127.0.0.1:27182/api/health
Verify
~/.claude.jsonhas theroampal-coreMCP entry with correct Python pathCheck Claude Code output panel for MCP errors
Make sure you ran
roampal init --opencodeCheck that the server auto-started:
curl http://127.0.0.1:27182/api/healthIf not, start it manually:
roampal start
This is expected. Roampal has self-healing -- if the HTTP server stops responding, it is automatically restarted and retried.
Still stuck? Ask your AI for help — it can read logs and debug Roampal issues directly.
Support
Roampal Core is completely free and open source.
Support development: roampal.gumroad.com
Feature ideas & feedback: Discord
Bug reports: GitHub Issues
Need help with AI memory? Reach out: roampal@protonmail.com | LinkedIn