https://github.com/roampal-ai/roampal-core
Outcome-based persistent memory MCP server for Claude Code and OpenCode. Good advice promoted, bad advice demoted. pip install roampal.
https://github.com/roampal-ai/roampal-core
agent-memory ai-assistant ai-coding ai-coding-assistant ai-memory ai-tools chromadb claude-code coding-assistant developer-tools llm long-term-memory mcp mcp-server memory model-context-protocol opencode persistent-memory python semantic-search
Last synced: 12 days ago
JSON representation
Outcome-based persistent memory MCP server for Claude Code and OpenCode. Good advice promoted, bad advice demoted. pip install roampal.
- Host: GitHub
- URL: https://github.com/roampal-ai/roampal-core
- Owner: roampal-ai
- License: apache-2.0
- Created: 2025-12-15T23:26:55.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-04-09T19:22:25.000Z (17 days ago)
- Last Synced: 2026-04-09T21:16:45.837Z (17 days ago)
- Topics: agent-memory, ai-assistant, ai-coding, ai-coding-assistant, ai-memory, ai-tools, chromadb, claude-code, coding-assistant, developer-tools, llm, long-term-memory, mcp, mcp-server, memory, model-context-protocol, opencode, persistent-memory, python, semantic-search
- Language: Python
- Homepage: https://roampal.ai
- Size: 1.3 MB
- Stars: 40
- Watchers: 0
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# 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.
### Benchmarks
**85.8% on LoCoMo** (non-adversarial, end-to-end answer accuracy) — validated on 1,986 questions across 10 conversations with dual grading.
| Result | Score |
|--------|-------|
| Conversational learning vs raw ingestion | **+23 points** (76.6% vs 53.0%, p<0.0001) |
| Architecture vs model effect | Architecture **~10x larger** contributor |
| Poison resilience (1,135 adversarial memories) | **-2.6 to -4.2 points** only |
| TagCascade retrieval (tags-first + CE rerank) | **+1.9 Hit@1** vs pure CE (p<0.0001) |
Benchmark pipeline runs on a single GPU with no cloud dependencies. Roampal itself runs on CPU — no GPU required. Full methodology, data, and evaluation scripts: [roampal-labs](https://github.com/roampal-ai/roampal-labs)
Paper: *"Beyond Ingestion: What Conversational Memory Learning Reveals on a Corrected LoCoMo Benchmark"* (Logan Teague, April 2026)
---
## Quick Start
```bash
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`
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
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
```bash
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 # Add documents to books collection
roampal books # List all ingested books
roampal remove # Remove a book by title
roampal sidecar status # Check scoring model configuration (OpenCode)
roampal sidecar setup # Configure scoring model (OpenCode)
roampal sidecar test # Test scoring model response format (OpenCode)
roampal retag # Re-extract tags on memories using sidecar LLM
roampal sidecar disable # Remove scoring model configuration (OpenCode)
```
## MCP Tools
Your AI gets these memory tools:
| Tool | Description | Platforms |
|------|-------------|-----------|
| `search_memory` | Deep search across all collections | Both |
| `add_to_memory_bank` | Store permanent facts (identity, preferences, goals) | Both |
| `update_memory` | Correct or update existing memories | Both |
| `delete_memory` | Remove outdated info | Both |
| `score_memories` | Score previous exchange outcomes | Claude Code |
| `record_response` | Store key takeaways from significant exchanges | Both |
> **How scoring works:** Claude Code's hooks prompt the main LLM to call `score_memories` every turn. OpenCode uses an independent sidecar that scores silently in the background — the model never sees a scoring prompt and `score_memories` is not registered as a tool. If the sidecar is unavailable, a warning prompts the user to run `roampal sidecar setup`. Choose your scoring model during `roampal init` or via `roampal sidecar setup`.
## How Roampal Compares
| Feature | Roampal Core | Claude Code built-in (CLAUDE.md / auto memory) | OpenCode built-in |
|---------|-------------|--------------------------------------------------|-------------------|
| Learns from outcomes | Yes — bad advice demoted, good advice promoted | No | No |
| Semantic retrieval | Yes — TagCascade + cross-encoder reranking | No — files loaded in full, no search | No memory system |
| Context injection | Automatic — relevant memories per query | Full CLAUDE.md every session, auto memory on demand | None |
| Atomic fact extraction | Yes — summaries + facts, two-lane retrieval | No — saves what Claude decides is useful | No |
| Works across projects | Yes — shared memory across all projects | Per-project only (per git repo) | No memory |
| Scales with history | Yes — 5 collections, promotion/demotion/decay | CLAUDE.md unbounded, auto memory first 200 lines | No memory |
| Fully local / private | Yes — ChromaDB on your machine | Yes | Yes |
Architecture
```
┌─────────────────────────────────────────────────────────┐
│ 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/`](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)
- **RAM:** ~800MB available (cross-encoder reranker + embeddings + ChromaDB)
- **Disk:** ~500MB for models (multilingual embedding + reranker, downloaded automatically on first use)
- **CPU:** Any modern x86-64 processor with AVX2 (Intel Haswell 2013+ / AMD Excavator 2015+)
- **GPU:** Not required — all inference runs on CPU via ONNX Runtime
## Troubleshooting
Hooks not working? (Claude Code)
- Restart Claude Code (hooks load on startup)
- Check HTTP server: `curl http://127.0.0.1:27182/api/health`
MCP not connecting? (Claude Code)
- Verify `~/.claude.json` has the `roampal-core` MCP entry with correct Python path
- Check Claude Code output panel for MCP errors
Context not appearing? (OpenCode)
- 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`
Server crashes and recovers?
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](https://roampal.gumroad.com/l/aagzxv)
- Feature ideas & feedback: [Discord](https://discord.com/invite/F87za86R3v)
- Bug reports: [GitHub Issues](https://github.com/roampal-ai/roampal-core/issues)
- Need help with AI memory? Reach out: **roampal@protonmail.com** | [LinkedIn](https://www.linkedin.com/in/logan-teague-6909901a5/)
## License
[Apache 2.0](LICENSE)