roampal-core

Paper:"Beyond Ingestion: What Conversational Memory Learning Reveals on a Corrected LoCoMo Benchmark"(Logan Teague, April 2026)

Auto-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 prompts the main LLM to score each exchange via thescore_memoriestool. OpenCode never self-scores — an independent sidecar (a separate API call) reviews each exchange as a third party, removing self-assessment bias. Thescore_memoriestool is not registered on OpenCode. Scoring is disabled by default until you explicitly configure it viaroampal 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.8:Crash-resilience release — enables SQLite WAL + FULL durability on the ChromaDB catalog so hard terminations (Windows port conflicts, external process kills, power loss) no longer corrupt or empty the database. RewritesSessionManager.mark_scored()to perform an atomic temp-file replace, guaranteeing the JSONL transcript survives a crash mid-write. Also ships 16 new automated tests covering both fixes, fixes pre-existing test debt that left the full suite red on Windows, and adds dev tooling (pytest-timeout,pytest-forked,build,twine). No data migration required; WAL is applied on the next server start.

v0.5.7:Startup garbage collection for the MCP hook's_completion_state.json. The file accumulated one entry perconversation_idever seen with no cleanup, driving I/O amplification on every write and leaving stuckscored_this_turn=Trueflags that could poison the cross-session scoring fallback. New_cleanup_completion_statepass drops entries older than 30 days or with no matching transcript, enforces a 500-entry hard ceiling, and writes atomically. JSONL transcript TTL bumped 7 → 30 days to stay in lockstep with the state-file TTL. Ships paired with Roampal Desktop v0.3.3.

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'sdirectoryviaclient.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 withstatus=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 anX-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.

When you type a message, Roampal automatically injects relevant context before your AI sees it:

- Python 3.10+
- One of:Claude CodeorOpenCode
- 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

- 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 path
- Check Claude Code output panel for MCP errors

- Make sure you ranroampal 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, it is automatically restarted and retried.

Still stuck?Ask your AI for help — it can read logs and debug Roampal issues directly.

Roampal Core is completely free and open source.

Persistent memory for any AI assistant. Zero token cost until recall. Stores memories in local SQLite, ranks by 6-factor scoring, returns results 79% smaller than JSON. Works with Claude, ChatGPT, Grok, Cursor, Windsurf, and any MCP client.

After Effects MCP is a full-featured automation bridge that connects AI clients (like VS Code, Claude Desktop, and Claude Code) to Adobe After Effects through MCP, enabling scripted control of compositions, layers, effects, keyframes/graph easing, presets, markers, audio levels, waveform analysis, and effect discovery via a live bridge panel.

Project management your AI can actually run — connect Claude, ChatGPT, Cursor & Codex to one board over MCP.

AIOProductOS spine over MCP — customers, revenue, feedback, work, analytics on one typed record.

The memory layer for AI coding tools. Local-first, semantic, 9 MCP tools with consolidation and project scoping. Works with Claude Code, Cursor, Windsurf & any MCP client.

One MCP server for Claude, ChatGPT & Gemini — wraps your ERPs, CRMs, APIs and knowledge base into a single governed endpoint.

Run your field service business from Claude: answer calls, book and dispatch jobs, build estimates, chase invoices. Built for HVAC, plumbing, electrical, roofing and pest control.

Complete Swiss accounting integration for Bexio via MCP. Works with Claude Desktop, n8n, and any MCP client. 221 tools for invoices, contacts, projects & more.

Persistent memory MCP server for Claude Desktop — remembers context, time, and topics across sessions