Outcome-based persistent memory for AI coding tools.
Roampal — Outcome-Based Persistent Memory MCP Server
Two commands. Your AI coding assistant gets outcome-based memory. Works with Claude Code and OpenCode.
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 init
Auto-detects installed tools. Restart your editor and start chatting.
Target a specific tool:
roampal init --claude-codeorroampal init --opencode
Platform Differences
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 session.idle event |
| Scoring | Main LLM via score_memories tool |
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 bug
Your 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 bug
No 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 |
|---|---|---|
working |
Current session context | 24h — promotes if useful, deleted otherwise |
history |
Past conversations | 30 days, outcome-scored |
patterns |
Proven solutions | Persistent while useful, promoted from history |
memory_bank |
Identity, preferences, goals | Permanent |
books |
Uploaded reference docs | Permanent |
Commands
roampal init # Auto-detect and configure installed tools
roampal init --claude-code # Configure Claude Code explicitly
roampal init --open
Tools (1)
score_memoriesPromotes or demotes memory items based on the outcome of an AI exchange.Configuration
{"mcpServers": {"roampal": {"command": "roampal", "args": ["serve"]}}}