Roampal MCP Server

Roampal — Outcome-Based Persistent Memory MCP Server

<strong>Two commands. Your AI coding assistant gets outcome-based memory.</strong> Works with <strong>Claude Code</strong> and <strong>OpenCode</strong>.

---

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-code or roampal init --opencode

<details> <summary><strong>Platform Differences</strong></summary>

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.

</details>

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

1. You type a message
2. Roampal injects relevant context automatically (hooks in Claude Code, plugin in OpenCode)
3. AI responds with full awareness of your history, preferences, and what worked before
4. Outcome scored — good advice gets promoted, bad advice gets demoted
5. 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