roampal-core

Persistent memory for Claude Code with outcome-based learning. Tracks what helped vs failed, auto-injects context via hooks.

GitHub

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 fixes this with outcome-based memory. Good advice gets promoted. Bad advice gets demoted. Your AI gets smarter every exchange, across every session.

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

The core loop is identical — both platforms inject context, capture exchanges, and score outcomes. The delivery mechanism differs:

Claude CodeOpenCode
Context injectionHooks (stdout)Plugin (system prompt)
Exchange captureStop hookPlugin session.idle event
ScoringMain LLM prompted via hooksMain LLM prompted + independent sidecar fallback
Self-healingHooks auto-restart server on failurePlugin auto-restarts server on failure

Both platforms prompt the main LLM to score each exchange. OpenCode adds an independent sidecar call (using free models) as a fallback — sidecar only runs if the main LLM doesn't call score_memories, so memories are never double-scored.

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

CollectionPurposeLifetime
workingCurrent session context24h — promotes if useful, deleted otherwise
historyPast conversations30 days, outcome-scored
patternsProven solutionsPersistent while useful, promoted from history
memory_bankIdentity, preferences, goalsPermanent
booksUploaded reference docsPermanent

Commands

roampal init                # Auto-detect and configure installed tools
roampal init --claude-code  # Configure Claude Code explicitly
roampal init --opencode     # Configure OpenCode explicitly
roampal start               # Start the HTTP server manually
roampal stop                # Stop the HTTP server
roampal status              # Check if server is running
roampal stats               # View memory statistics
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

MCP Tools

Your AI gets 6 memory tools:

ToolDescription
search_memoryDeep search across all collections
add_to_memory_bankStore permanent facts (identity, preferences, goals)
update_memoryCorrect or update existing memories
delete_memoryRemove outdated info
score_memoriesScore previous exchange — prompted automatically by hooks
record_responseStore key takeaways from significant exchanges

What's Different?

Without RoampalWith Roampal
Forgets everything between sessionsRemembers you, your preferences, what worked
You repeat context every timeContext injected automatically
No learning from mistakesOutcomes tracked — bad advice gets demoted
No document memoryIngest docs, searchable forever

Benchmarks

Tested across 10 adversarial scenarios designed to trick similarity search (200 total tests):

ConditionTop-1 Accuracy
RAG baseline (vector search only)10%
+ Cross-encoder reranking20%
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

FeatureRoampal Core.cursorrules / CLAUDE.mdMem0
Learns from outcomesYes — bad advice demoted, good advice promotedNoNo
Zero-config context injectionYes — hooks inject automaticallyManual file editingAPI calls required
Works across sessionsYes — 5 memory collections with promotionPer-project static filesYes
Fully local / privateYes — all data on your machineYesCloud or self-hosted
Open sourceApache 2.0N/AApache 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          │
│    → Server returns context + scoring prompt            │
│    → AI sees context, scores previous, responds         │
│    → Exchange stored for next turn                      │
└─────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│  Single-Writer Backend                                  │
│    FastAPI → UnifiedMemorySystem → ChromaDB             │
│    All clients share one server, isolated by session    │
└─────────────────────────────────────────────────────────┘

See ARCHITECTURE.md 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.json has the roampal-core MCP entry with correct Python path
  • Check Claude Code output panel for MCP errors
  • Make sure you ran roampal init --opencode
  • Check that the server auto-started: curl http://127.0.0.1:27182/api/health
  • If not, start it manually: roampal start

This is expected. Roampal has self-healing — if the HTTP server stops responding, hooks automatically restart it and retry.

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.

License

Apache 2.0

Related Servers