roampal-ai/roampal-core

v0.5.7 Breaking

This release includes breaking changes for platform teams planning a safe upgrade.

Published 22d MCP Developer Tools

View tool

✓ No known CVEs patched

Read the diff → Tool health → What is this tool? →

✓ No known CVEs patched in this version

Topics

agent-memory ai-assistant ai-coding ai-coding-assistant ai-memory ai-tools

+14 more

chromadb claude-code coding-assistant developer-tools llm long-term-memory mcp mcp-server memory model-context-protocol opencode persistent-memory python semantic-search

Affected surfaces

breaking_upgrade

ReleasePort's take

Light signal

editorial:auto 13d

v0.5.7 implements automatic cleanup for _completion_state.json with 500-entry cap and 30-day TTL, fixing unbounded growth and I/O amplification on long-running installs.

Why it matters: Long-running installations no longer accumulate unbounded state entries, reducing I/O overhead. Automatic cleanup with sensible defaults (500 max entries, 30-day retention) prevents operational degradation without manual intervention.

Summary

AI summary

Fixed unbounded growth in _completion_state.json causing I/O amplification and stale scoring flags.

Changes in this release

Type	Severity	Summary	CVE
Security	Medium	Fixed unbounded-growth defect in MCP hook's per-conversation lifecycle file, mitigating potential ID-collision risks. Fixed unbounded-growth defect in MCP hook's per-conversation lifecycle file, mitigating potential ID-collision risks. Source: llm_adapter@2026-05-21 Confidence: high	—
Feature	Medium	SessionManager.__init__ invokes _cleanup_completion_state with max_age_days=30 and max_entries=500. SessionManager.__init__ invokes _cleanup_completion_state with max_age_days=30 and max_entries=500. Source: llm_adapter@2026-05-21 Confidence: low	—
Feature	Low	Coordinates with Roampal Desktop v0.3.3 to unlink `_completion_state.json` during GUI bulk-clear operations. Coordinates with Roampal Desktop v0.3.3 to unlink `_completion_state.json` during GUI bulk-clear operations. Source: granite4.1:30b@2026-05-23-audit Confidence: low	—
Performance	Medium	Capped _completion_state.json entries to 500, reducing I/O amplification on long-running installs. Capped _completion_state.json entries to 500, reducing I/O amplification on long-running installs. Source: llm_adapter@2026-05-21 Confidence: high	—
Bugfix
Bugfix	Medium	_completion_state.json startup GC now runs periodic cleanup to prevent unbounded growth and associated issues. _completion_state.json startup GC now runs periodic cleanup to prevent unbounded growth and associated issues. Source: llm_adapter@2026-05-21 Confidence: low	—
Bugfix	Medium	Cleans up unbounded growth in `_completion_state.json` during SessionManager initialization. Cleans up unbounded growth in `_completion_state.json` during SessionManager initialization. Source: granite4.1:30b@2026-05-23-audit Confidence: low	—
Bugfix	Medium	Adds atomic write and logging of prune count in `_cleanup_completion_state` to prevent partial state on crash. Adds atomic write and logging of prune count in `_cleanup_completion_state` to prevent partial state on crash. Source: granite4.1:30b@2026-05-23-audit Confidence: low	—
Bugfix	Medium	Fixes stuck `scored_this_turn=True` flags from long-dead sessions that could poison cross-session scoring fallback. Fixes stuck `scored_this_turn=True` flags from long-dead sessions that could poison cross-session scoring fallback. Source: granite4.1:30b@2026-05-23-audit Confidence: low	—
Refactor	Medium	JSONL transcript TTL increased from 7 days to 30 days for consistent cleanup timing. JSONL transcript TTL increased from 7 days to 30 days for consistent cleanup timing. Source: llm_adapter@2026-05-21 Confidence: low	—
Other	Medium	ARCHITECTURE.md updated with removed Knowledge Graphs section, rewritten Search Pipeline, corrected fix descriptions, and added missing endpoints CLI flags dev-deps. ARCHITECTURE.md updated with removed Knowledge Graphs section, rewritten Search Pipeline, corrected fix descriptions, and added missing endpoints CLI flags dev-deps. Source: llm_adapter@2026-05-21 Confidence: low	—
Other	Low	Adds four new tests in `test_session_manager.py` covering stale-timestamp prune, missing-JSONL prune, 500-entry ceiling, and atomic-write contract. Adds four new tests in `test_session_manager.py` covering stale-timestamp prune, missing-JSONL prune, 500-entry ceiling, and atomic-write contract. Source: granite4.1:30b@2026-05-23-audit Confidence: low	—

Full changelog

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 sessions that could poison the cross-session scoring fallback and falsely mark live turns as already-scored
Latent ID-collision risk when client-supplied conversation IDs recur

SessionManager.__init__ now runs _cleanup_completion_state(max_age_days=30, max_entries=500) alongside the existing transcript and exchange-cache passes:

Drops entries where first_message_timestamp is older than 30 days OR the matching <conversation_id>.jsonl transcript is missing
Evicts oldest by timestamp until count ≤ 500
Writes once atomically at the end (no partial state on crash)
Logs prune count on every startup — never silent on installs that have a state file

The JSONL transcript TTL was also bumped from 7 days to 30 days so the two cleanups stay in lockstep — a paused conversation that still has its transcript on disk won't get pruned out from under itself.

Documentation sync

ARCHITECTURE.md cleanup of accumulated drift across v0.3.5 → v0.5.6: removed the dead Knowledge Graphs section (KG was removed in v0.4.5), rewrote the Search Pipeline section (BM25 + RRF was removed in v0.4.1.2 — current pipeline is TagCascade + CE rerank), corrected the inverted $contains fix description, brought the score_memories API examples up to the v0.5.6 shape (memory_scores / exchange_summary / exchange_outcome / noun_tags), fixed Claude Code init paths and OpenCode MCP config shape, added missing endpoints + CLI flags + dev-deps. Benchmark numbers now cited inline to roampal-labs/paper.md §5.2.3.

Coordination

Ships paired with Roampal Desktop v0.3.3, which automates the "delete _completion_state.json and restart" manual workaround at GUI bulk-clear time (Section 9.1 — unlinks the state file after working/history/patterns clears). The two layers together close the cross-session fallback misrouting path: 9.1 unlinks the file at user-triggered clear; v0.5.7 trims accumulated entries at every startup.

Tests

720 tests pass (roampal/ full suite): 624 memory-module unit + 29 memory-module integration + 67 other unit tests including test_profile_manager and test_cache_eviction. 4 new tests in test_session_manager.py cover stale-timestamp prune, missing-JSONL prune, 500-entry ceiling after age pass, and the atomic-write contract on simulated os.replace failure.

Install

pip install --upgrade roampal==0.5.7

View diff on GitHub

Weekly OSS security release digest.

The CVE patches and breaking changes that affected production tools this week. One email, every Sunday.

No spam, unsubscribe anytime.

Share this release

Share on X Share on Bluesky

Track roampal-ai/roampal-core

Get notified when new releases ship.

About roampal-ai/roampal-core

Outcome-based persistent memory for AI coding tools. Memories that help get promoted, memories that mislead get demoted. Works with Claude Code and OpenCode via hooks + MCP.

All releases →