# roampal-core

> Outcome-based persistent memory MCP server for Claude Code and OpenCode. Good advice promoted, bad advice demoted. pip install roampal.

- **URL**: https://www.freshcrate.ai/projects/roampal-core
- **Author**: roampal-ai
- **Category**: MCP Servers
- **Latest version**: `v0.5.7` (2026-05-12)
- **License**: Apache-2.0
- **Source**: https://github.com/roampal-ai/roampal-core
- **Homepage**: https://roampal.ai
- **Language**: Python
- **GitHub**: 44 stars, 6 forks
- **Registry**: github
- **Tags**: `agent-memory`, `ai-assistant`, `ai-coding`, `ai-coding-assistant`, `ai-memory`, `ai-tools`, `chromadb`, `claude-code`, `python`

## Description

Outcome-based persistent memory MCP server for Claude Code and OpenCode. Good advice promoted, bad advice demoted. pip install roampal.

## Recent releases

| Version | Date | Urgency | Changes |
| --- | --- | --- | --- |
| `v0.5.7` | 2026-05-12 | High | Hardening release. No new user-visible features. Closes an unbounded-growth defect in the MCP hook's per-conversation lifecycle file (`_completion_state.json`) that surfaced during issue #8 repro.  ## What's fixed  **`_completion_state.json` startup GC** — the file accumulated one entry per `conversation_id` ever seen, with no cleanup. On long-running installs this drove:  - I/O amplification (full-file rewrite on every state mutation) - Stuck `scored_this_turn=True` flags from long-dead session |
| `v0.5.6` | 2026-05-01 | High | Hardening release closing coverage gaps from the v0.5.5.x verification audit. No new user-visible features.  ## Memory phantoms (#8 follow-up) — items 5-11, 32 - `_sweep_phantoms()` runs after `cleanup_archived()`, not just at startup - chromadb_adapter phantom filter strengthened (AND → OR mid-state catch) - Status backfill on startup for legacy entries - Auto-trigger `cleanup_archived()` under capacity pressure - Dedup observability log on every dedup-skip - Lane enforcement: `delete()` → `del |
| `v0.5.5` | 2026-04-27 | High | ## Roampal Core v0.5.5 — 2026-04-27  **Bugfix release.** Fixes issue #8 where GUI deletion of memories blocks new memory generation.  ### What's Fixed - **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=archived metadata update plus status filter on all query/dedup paths. - **Scoring mutex to async queue** — Eliminates dropped scoring requests that caused |
| `v0.5.3.1` | 2026-04-23 | High | ## Hotfix for v0.5.3 — facts and summary extraction broken on thinking models  Three bugs in the OpenCode plugin's JSON extraction logic. All three only manifested with reasoning/thinking models on local sidecar setups.  ### What was broken  **Bug 1 — Facts extraction silently failing on every exchange (latent since v0.4.8).** The facts extraction path used a greedy regex that swallowed trailing markdown code fences. Models that wrap JSON in ` ```json ... ``` ` blocks broke `JSON.parse()` with ` |
| `v0.5.2` | 2026-04-21 | High | # Roampal Core v0.5.2  **Release Date:** 2026-04-21 **Type:** Patch — chat-path performance, field-drift lifecycle fix, v0.5.1 profile-resolution bugfixes **Coordination:** Core ships first; Desktop v0.3.2 follows with the same latency trio and age-gate fix applied to the Tauri backend  ## Summary  Three bundled improvements:  1. **Performance (Sections 1–3)** — cut the per-message latency added by the    memory pipeline on every MCP tool call. Beta feedback on Desktop v0.3.1    (2026-04-17) fla |
| `v0.5.1` | 2026-04-17 | High | # Roampal Core v0.5.1 Release Notes  **Release Date:** TBD **Type:** Minor — named memory profiles + sidecar consistency patch  ## Summary  Two changes bundled:  1. **Named memory profiles** (feature) — support multiple isolated memory stores per user, switchable per command, per shell, per project (MCP config), or globally. 2. **Sidecar scoring cap** (patch) — cap exchange fields at 8K characters in the scoring prompt, matching the fact-extraction call.  ---  ## 1. Named Memory Profiles  ### Mo |
| `v0.5.0` | 2026-04-16 | High | ## Summary  v0.5.0 addresses five issues in the OpenCode plugin:  1. **Subagent filtering** (Issue #4): Subagent exchanges no longer pollute the memory store 2. **OpenAI sidecar fix**: Removed `think: false` field that broke all non-Ollama sidecar targets 3. **Sidecar input cap**: Bumped fact extraction input from 800 chars to 16K (8K + 8K) 4. **Summary output cap**: Bumped scoring prompt summary limit from 300 chars to 2000 chars 5. **Scoring status visibility**: Replaced boolean `scoringBroken |
| `v0.4.9.2` | 2026-04-14 | High | ## Summary  Rewrite all 6 MCP tool descriptions for Glama TDQS (Tool Definition Quality Score) compliance.  ### Changes  Every tool description now includes: - **BEHAVIOR** section — explicit state changes, what gets created/modified/deleted - **ERROR HANDLING** section — what happens on invalid input, no matches, empty results - **WHEN NOT TO USE** section — clear disambiguation between tools - **Parameter examples** — concrete examples for every parameter  ### Previous Glama Scores  \| Tool \| G |
| `v0.4.9.1` | 2026-04-14 | High | ## Hotfix  Critical fix for server deadlock on startup and leftover regex tag fallback shipped in v0.4.9.  ### Fixes  - **Server deadlock on startup** — A v0.4.8 migration block ran on every boot inside the async `lifespan()` function, pulling up to 30,000 facts from ChromaDB via synchronous calls. With large datasets this blocked the event loop indefinitely — the server bound the port but never served requests. All hooks timed out silently. Removed entirely; use `roampal retag` instead. - **Reg |
| `v0.4.9` | 2026-04-14 | High | ## Summary  Fixes critical sidecar robustness issues and achieves full benchmark alignment for tag extraction.  ### Key Changes  - **Wire TagService to sidecar LLM** — v0.4.8 had `extract_tags()` in code but never called it. Tags were silently falling back to regex. Now properly wired for OpenCode sidecar scoring. - **Remove regex tag extraction** — LLM-only tags matching benchmark behavior. If LLM fails, returns `[]` (no fallback). Use `roampal retag` to clean up existing memories. - **Robust b |

## Citation

- HTML: https://www.freshcrate.ai/projects/roampal-core
- Markdown: https://www.freshcrate.ai/projects/roampal-core.md
- Dependencies JSON: https://www.freshcrate.ai/api/projects/roampal-core/deps

_Generated by freshcrate.ai. Indexes github releases for AI-agent ecosystem packages._