roampal-core
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
Paper: "Beyond Ingestion: What Conversational Memory Learning Reveals on a Corrected LoCoMo Benchmark" (Logan Teague, April 2026)
Related MCP server: total-recall
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, disabled by default until configured) |
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. Scoring is disabled by default until you explicitly configure it via roampal sidecar setup. During setup, Roampal detects local models (Ollama, LM Studio, etc.) and lets you choose a scoring model. Zen free models are available as an explicit opt-in choice for users without a local model or API key — they route through OpenCode's proxy which may log data. A cheap or local model works great — scoring doesn't need a powerful model.
v0.5.6: Hardening release — closes remaining coverage gaps from the v0.5.5.x verification audit. Phantom sweep after archived cleanup, auto-cleanup under capacity pressure, dedup observability, hardened delete permissions, archive-then-add cycle tests, sidecar prompt alignment with benchmark, async scoring queue (per-session deferred retry), MCP tool definition quality rewrite (TDQS), OpenCode Go auto-detect in sidecar setup wizard, and user name extraction fix.
v0.5.5.2: Hotfix — Windows plugin install now verifies copy succeeded (post-copy size check + manual read/write fallback for OneDrive/antivirus interference). Also installs to
%APPDATA%\opencode\pluginsas fallback since some Electron apps resolve config paths differently on Windows. Fixes remaining cases of issue #11 whereroampal init --forcereported success but the plugin was empty or in the wrong directory.v0.5.5.1: Hotfix — OpenCode Desktop now correctly switches profiles when you switch projects in the UI (issue #10). Plugin reads the active session's
directoryviaclient.session.get()instead of caching the profile at module load, so a singleton plugin across a multi-project workspace still hits the right profile per message. Also:roampal init --forceactually overwrites the OpenCode plugin file now (issue #11), with clearer errors when Desktop holds a file lock.v0.5.5: Soft-delete for memory_bank — ChromaDB hard delete doesn't actually remove vectors from HNSW, causing phantom dedup matches that block new memories after GUI deletion. Replaced with
status=archivedmetadata update plus status filter on all query/dedup paths. Also: scoring mutex → async queue (eliminates dropped requests), sidecar summary contamination fix (delimiter fencing).v0.5.4: Profile binding is now per-request, not per-process. Every client (MCP server, OpenCode plugin, Python hooks for Claude Code / Cursor) sends an
X-Roampal-Profileheader so a single FastAPI server can cleanly serve multiple profiles simultaneously. Fixes issue #7 where OpenCode Desktop's per-projectROAMPAL_PROFILEinopencode.jsonwas ignored because the singleton FastAPI bound the profile once at startup.v0.5.3: Sidecar scoring now requires explicit configuration (no automatic fallback to Zen or localhost). Small local models (qwen2.5:3b, etc.) that return bare JSON arrays instead of OpenAI-shaped responses are handled transparently via server-side shape tolerance.
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 test # Test scoring model response format (OpenCode)
roampal retag # Re-extract tags on memories using sidecar LLM
roampal sidecar disable # Disable scoring (removes config, retrieval still works)
# Sidecar scope flags (v0.5.3+) — OpenCode merges project-local over user-global config:
roampal sidecar setup --scope user # Write only to user-global config (~/.config/opencode/)
roampal sidecar setup --scope project # Write only to project-local opencode.json in cwd ancestry
roampal sidecar setup # Auto-detects: uses project-local if shadow exists, otherwise user-global
# Sidecar scope flags for disable (v0.5.3+):
roampal sidecar disable --scope user # Clear only from user-global config
roampal sidecar disable --scope project # Clear only from project-local opencode.json
roampal sidecar disable # Auto-detects scope same as setup
# Named memory profiles (v0.5.1) — isolate memory per project, per client, etc.
roampal profile list # List registered profiles
roampal profile show # Show active profile and its path
roampal profile create <name> # Create auto-located profile
roampal profile register <name> --path <dir> # Register an existing directory
roampal profile use <name> # Persist as user-global default
roampal profile unuse # Clear persistence
roampal profile switch <name> # Persist + kill running server
roampal profile delete <name> # Remove from registry
roampal start --profile <name> # One-off launch on a profileNamed Memory Profiles (v0.5.1)
Run separate memory stores for different contexts — per project, per client (Claude Code vs OpenCode), work vs home. Profiles are managed entirely through the CLI; no config files to hand-edit.
roampal profile create work # auto-located at <appdata>/Roampal/data/work/
roampal profile switch work # persist + kill running server
# next MCP tool call spawns a fresh server on 'work'Register an existing directory as a profile (no data migration):
roampal profile register project-a --path /existing/custom/pathPrecedence (highest wins):
--profile <name>flagROAMPAL_PROFILE=<name>env var (set per-project inopencode.jsonor.claude.jsonenv: {})roampal profile use <name>persisted default"default"fallback
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.
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 |
┌─────────────────────────────────────────────────────────┐
│ 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)
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
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
License
Available Tools
6 toolsadd_to_memory_bankA
Store permanent facts about the user
Inputs: content (required).
delete_memoryC
Delete a memory by ID
Inputs: memory_id (required).
record_responseA
Store key takeaways from significant exchanges. NOT for permanent preferences or standing rules — use add_to_memory_bank for those.
Inputs: key_takeaway (required).
score_memoriesD
Score previous exchange outcomes
Inputs: memory_scores (required).
search_memoryB
Search across memory collections for relevant context
Inputs: query (required).
update_memoryC
Update an existing memory
Inputs: content (required), memory_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool targets a distinct operation: permanent facts, exchange takeaways, scoring, search, update, and delete. Descriptions clearly differentiate purposes, leaving no ambiguity for an agent.
All tool names follow a consistent verb_noun or verb_preposition_noun pattern in snake_case, ensuring predictability and clarity.
With 6 tools covering the core operations of a memory system, the count is well-scoped—neither too few nor excessive for the domain.
The set provides complete CRUD (create via add_to_memory_bank and record_response, read via search_memory, update via update_memory, delete via delete_memory) plus an additional scoring capability, leaving no obvious gaps.
Maintenance
Related MCP Connectors
Persistent memory and cross-session learning for AI coding assistants (hosted remote MCP).
Persistent engineering memory designed to follow developers across coding agents.
Evidence-backed project memory and checkpoints for AI coding agents.
Adaptive plan/build/review cycles for AI coding assistants, persisted across sessions.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenancePersistent memory for AI coding agents1,271 PyPI226Apache 2.0
- AlicenseNot gradedqualityBmaintenancePersistent, cross-tool memory for AI coding assistants, enabling context retention across sessions, tools, and devices with a three-tier memory model and hybrid search.2,451 npm15MIT
- AlicenseNot gradedqualityDmaintenancePersistent cross-session memory for AI coding assistants, automatically capturing and injecting context across sessions via MCP tools.13 npm11AGPL 3.0
- AlicenseNot gradedqualityDmaintenancePersistent memory for AI coding tools, enabling AI assistants to store and recall project decisions, conventions, and context across sessions.59 npmMIT