Stability proposal: release cadence, migration guards, and graceful degradation

[superbiche]

@thedotmack — I'm tagging you directly because I think this conversation matters for the project's future.

The situation

claude-mem has become essential infrastructure for my daily workflow. I have 4,400+ observations across dozens of projects, accumulated over weeks of work. This data is my long-term memory across sessions — losing access to it means losing context that took real time to build.

I'm writing this because I want this project to succeed, and I think the current release pace is putting that at risk.

What happened to me

I was on v9.0.16. Upgraded to v10.3.1. After the upgrade:

• chroma-mcp immediately failed to connect on startup (MCP error -32000: Connection closed)
• Backfill couldn't sync — 25 projects stuck, zero vector search
• The search MCP tool returned results, but almost empty — 1 result for "hermes" when there should be 30+
• Root cause: the v10.x code routes all text queries through Chroma and returns empty arrays when Chroma fails instead of falling back to SQLite FTS (which has the data and works fine)
• The SQLite layer literally has: return E.warn("DB","Text search not supported - use ChromaDB for vector search"),[]

I had to downgrade back to v9, restore a database backup, and manually patch the minified worker-service.cjs to bypass Chroma and route text queries through SQLite FTS5. That patch took ~2 hours of reading minified code.

Rogue CLAUDE.md files

Separately, the isProjectRoot() logic has caused CLAUDE.md files to be created in subdirectories where they shouldn't exist (#793), including inside .git/ directories corrupting git refs (#1165). I had to build a dedicated cleanup skill in my workflow just to deal with this. Multiple users report 50-120+ rogue CLAUDE.md files per session. This has been a known issue since at least early February, with several related reports (#778, #734, #697, #641).

Chroma as a single point of failure

The current architecture makes Chroma a hard dependency for text search. This is risky because:

• Python version fragility. Chroma depends on Pydantic V1, which is incompatible with Python 3.14 (Python 3.14 incompatibility still present in v10.3.1: chroma-mcp fails without --python 3.13 #1196). Python 3.14 entered beta in October 2025 and ships as default on Homebrew/Fedora. The CLAUDE_MEM_PYTHON_VERSION setting exists but isn't actually used by the spawn code. This means any user whose system Python moves to 3.14 (which is happening now across distros) gets a completely broken claude-mem with no fallback.
• Platform fragility. Windows users hit uvx.cmd transport failures (Windows: chroma-mcp connection fails - uvx.cmd breaks MCP stdio transport #1190, Windows: Chroma MCP connection fails with uvx.cmd - use uvx instead #1192). macOS users hit CPU/memory leaks (chroma-mcp CPU/memory leak in v10.3.1 #1185). The Chroma integration surface area is enormous and platform-dependent.
• No graceful degradation. When Chroma fails, search returns empty results silently. No error, no fallback, no warning to the user. You just think your memory is empty.

Making the entire search pipeline depend on a chain of uvx -> chroma-mcp -> pydantic -> specific Python version is a fragile architecture for a tool that users depend on daily.

The broader pattern

Looking at the release history, this isn't an isolated incident:

Version	Date	What broke
v9.0.8	Jan 26	Zombie process accumulation — user reported 155 processes, 51GB RAM
v9.0.11	Jan 28	Observer session isolation broke authentication ("Invalid API key")
v9.0.12	Jan 28	Hotfix for v9.0.11 auth breakage
v10.2.3	Feb 17	ONNX model cache corruption from aggressive cache clearing
v10.2.4	Feb 18	Backfill created orphan Chroma collections per project instead of using shared collection
v10.2.5	Feb 18	Cache directory missing node_modules, semantic search broken
v10.3.0	Feb 18	Replaced WASM embedding with chroma-mcp — introduced timeouts, zombie workers, duplicate daemons
v10.3.1	Feb 19	Hotfix for v10.3.0 — still has connection failures, CPU/memory leaks

17 releases in 9 days (Feb 11-19). Currently 86 open issues, 38 tagged as bugs. Open issues include chroma-mcp CPU/memory leaks (#1185), Python 3.14 incompatibility (#1196), Windows connection failures (#1190, #1192), MetadataValue conversion errors (#1183), CLAUDE.md corruption inside .git/ (#1165), and duplicate observations (#1158).

Why this matters

People who adopt claude-mem don't just install it — they build workflows around it. The observations accumulate over weeks. The muscle memory of searching past context becomes part of how you work. When an upgrade silently breaks search (returning empty results instead of erroring), you don't notice immediately. You just think memory is empty. By the time you realize something is wrong, you've potentially lost observation coverage for sessions that ran during the broken period.

This is the kind of tool where stability matters more than features. I'd rather have reliable keyword search than broken vector search.

Concrete proposals

1. Graceful degradation, not silent failure. When Chroma/vector search is unavailable, fall back to SQLite FTS5 — don't return empty results. The FTS tables already exist and are maintained. I've implemented this in my fork (superbiche/claude-mem@fix/bypass-chroma-use-sqlite-fts) and it works.

2. Make Chroma opt-in, not required. SQLite FTS should be the default search backend. It's zero-dependency, cross-platform, and already indexed. Chroma/vector search should be an opt-in enhancement for users who want semantic search and are willing to manage the Python dependency. This eliminates the Python version, platform, and connection issues in one move.

3. Semantic versioning with actual meaning. A change that replaces the entire embedding backend (WASM to chroma-mcp) shouldn't be a patch version (10.2.x to 10.3.0). Major version bumps signal "test this before you trust it."

4. Slower release cadence for stable branch. Consider a stable branch that only gets releases after they've baked on main for a few days. Power users can opt into main; everyone else gets stability.

5. Migration guards. Before a release that changes the search backend or DB schema, verify that existing data is still queryable. A simple smoke test: insert 10 observations, upgrade, search for them, assert they're found.

6. Fix the CLAUDE.md placement logic. The isProjectRoot() function needs to walk up to find git roots, not just check the immediate directory. This has been causing repo pollution for weeks across multiple reports.

Closing

I forked and patched because I need this tool to work. I'd much rather contribute upstream than maintain a fork. But I can't keep upgrading if each version is a coin flip on whether my workflow survives.

With 29,500+ stars, this project has crossed the threshold from "cool experiment" to "infrastructure people depend on." That's a great position to be in — but it comes with the responsibility of not breaking things for the people who trusted you enough to build their workflows on your tool.

Happy to contribute the SQLite FTS fallback as a PR if there's interest.

[thedotmack]

I'm very interested in speaking with you about this because I need help maintaining the project successfully. Are you in our discord? Would you mind reaching out to me there?

[superbiche]

Just tried reaching out on your Discord but not sure it was the right profile. You can find me on it with the same nickname