Dicklesworthstone/cass_memory_system v0.5.0

cass-memory v0.5.0

on GitHub

Everything on main since 0.4.0. New commands and an auto-reflect hook, and two changed defaults (maxBulletsInContext, the context history window; see Changed), so it is a minor bump.

Added

• cm hook install --agent gemini: the same auto-reflect hook for Gemini CLI (.gemini/settings.json, same SessionEnd payload). cm hook status and cm doctor cover both agents.

• cm hook install|uninstall|status|session-end: auto-reflection. A Claude Code SessionEnd hook reflects each finished session in the background (cm reflect --session <transcript>, detached, logged to ~/.cass-memory/hooks.log). Transcripts of cm's own LLM subprocesses are skipped, and so are sessions that end inside a background reflect, so the hook cannot loop. Interactive cm init offers it. Other agents can call cm hook session-end --transcript <path>.

• cm playbook scrub --from-sessions <pattern>... | --cm-subprocess-calls [--deprecate-orphans] [--dry-run] removes feedback events and source references by session path, recounts them and re-derives maturity (never raising it), and backs up each playbook first (#77).

• cm playbook conflicts: pairs of active rules that contradict each other, with a keep/retire suggestion. cm context reports contradicting returned rules in conflicts and as a warning, and cm reflect notes new rules that contradict existing ones.

• cm context takes the task from piped stdin (echo "..." | cm context --json, or -).

• cm context --max-tokens <n> / MCP maxTokens, config contextTokenBudget (default 4000): a token budget for returned rules. Results carry retrieval stats.

• cm why runs the rule's search pointer (or its text) against cass and returns matching sessions as evidence (--no-history skips this). The top rules' pointers lead suggestedCassQueries.

• The curator detects reworded duplicates by embedding similarity (semanticDedupThreshold, default 0.75, calibrated on all-MiniLM-L6-v2: 0 of 14 related-but-distinct pairs merged, 7 of 15 rewordings caught) when semantic search is on. Rules whose directives disagree are never merged.

• Freebuff sessions are recognized (.freebuff/, ~/.config/freebuff/) and included in the default cross-agent allowlist (#69).

• cm diary <session> is registered. It was implemented but unreachable.

• Team playbook merge: cm playbook import matches rules by content as well as id. A teammate's copy of a rule (same text under another id, near-identical wording, or same id and text) merges into the existing rule. Feedback events are unioned without double counting, sources and tags are combined, and counts and maturity are recomputed. Imported rules that contradict existing ones are reported in conflicts.

• cm doctor Memory Quality checks: contradicting rules, feedback from cm's own LLM subprocess transcripts, and whether auto-reflection is installed, each pointing at the command that fixes it.

• MCP tools cm_why and cm_conflicts. memory_reflect takes agent.

• cm reflect --agent claude,codex: the option was missing from the CLI, and it now takes a comma list.

Fixed

• cm reflect, cm diary and hook-started reflects work with the OpenAI provider again. The upgraded OpenAI SDK sends strict structured outputs, which rejected the diary schema with HTTP 400 on every session. Requests that really go to OpenAI with strict json_schema (also when cm auto-falls back to OpenAI because the configured provider has no key) now use a strict-compliant diary schema; other providers, the CLI provider and disableStructuredOutputs keep the previous one.
• cm playbook export --yaml is accepted again (it is the default format). Dropping the flag broke scripts, and cm playbook export --yaml > backup.yaml left an empty file.
• Auto-reflect sessions that end together queue up: a hook-started reflect waits up to 30 minutes for the reflect in progress instead of giving up after 2 seconds and dropping its session.
• LLMs now receive the output schema. With ai 4 and the installed zod 3.25, the JSON schema sent to every provider was empty, so the reflector, validator, diary and audit models never saw the structure they had to produce, and only the post-hoc Zod check enforced it. After upgrading to ai 7 and zod 4, OpenAI gets strict json_schema, Anthropic gets native structured output where the model supports it, Google gets responseJsonSchema, and Ollama gets format: <schema>. The cli provider (claude/codex/gemini subprocess) now gets the full JSON Schema in its prompt instead of top-level field names.
• OpenAI requests stay on Chat Completions (.chat()), because AI SDK 5+ defaults to the Responses API, which OpenAI-compatible gateways do not implement. disableStructuredOutputs sends json_object with the schema in the prompt and validates with Zod.
• The curator's word-overlap dedup (and cm playbook import's content merge) folded "Never mock the database in unit tests" into "Mock the database in unit tests" (Jaccard 0.857), crediting the opposite advice. Rules whose directives disagree are never merged now, on either the lexical or the semantic path.
• cm reflect --workspace (and MCP memory_reflect workspace) now filters which sessions are reflected. It used to only choose the processed-log file, so every project's sessions were reflected. A session belongs to the workspace when cass reports it there, its Claude Code transcript folder is that directory's slug, or its transcript's first records carry a cwd inside it.
• cm hook install --global and doctor's Claude Code detection resolve ~ through HOME, as the rest of cm does. os.homedir() ignores later HOME changes under Bun.
• Inline // [cass: harmful b-x] - reason feedback from the shared converter put free text in the harmful-reason enum. It now goes in context, and the reflect pipeline uses that one converter.
• Tests are hermetic against ambient AWS/Ollama credentials and a missing cass binary.

Dependencies

• ai 4 → 7, @ai-sdk/openai|anthropic|google 1 → 4, @ai-sdk/amazon-bedrock 1 → 5, ollama-ai-provider → ollama-ai-provider-v2, zod 3 → 4, typescript 5 → 7, chalk 5 → 6, commander 14 → 15.

Removed

• Deprecated aliases loadToxicLog, appendToxicLog, isSemanticallyToxic.

Changed

• Context ranking (#89). Keyword relevance is BM25 over the playbook (IDF-weighted query coverage, light stemming, prefix matches). Feedback is a bounded multiplier in [1 - feedbackWeight, 1 + feedbackWeight] (default 0.1, a tiebreak among near-equally relevant rules), damped while marks are few. Measured on the retrieval benchmark (test/context-retrieval-benchmark.test.ts) against the old ranker run on the same data. Before, relevance was multiplied by the raw effective score, so an unmarked rule got ×0.1 and a well-marked one ×10 or more. A relative relevance floor minRelativeRelevance (default 0.2 × the best match) drops the long tail.
• maxBulletsInContext default 50 → 10 (#89).
• Bullets in cm context output are a compact projection: no feedback-event log, source-session list or embedding (cm playbook get <id> has the full record).
• cm context history searches historyLookbackDays (default 90) instead of sessionLookbackDays (7).
• Conflict detection works per clause, so a negation in an unrelated clause no longer flags a rule (the built-in starters went from 5 false positives to 0).

Known issues

• cm hook install at project scope (what cm init offers) writes the shared .claude/settings.json; if that file is committed, teammates with cm on PATH get auto-reflection without opting in (#90). Install with --global to keep the hook per user.

Gate

• tsc --noEmit: clean
• bun test --timeout 60000 --isolate, run file by file on Linux x64 with bun 1.4.2, compared with v0.4.0 on the same host: 2649 passed, 20 failed (the same 20 tests fail at v0.4.0 there). 13 files abort because bun 1.4.2 cannot load the sharp native module in a source checkout (12 of them at v0.4.0 too); compiled binaries load it optionally and are unaffected.
• Compiled binary (bun build --compile): init, doctor, context, playbook add/list/export, mark, why, stats, top and similar all succeed in a fresh home.

Artifacts

cass-memory-linux-x64, cass-memory-linux-arm64, cass-memory-macos-arm64, cass-memory-macos-x64, cass-memory-windows-x64.exe, each with a .sha256 sidecar, plus install.sh.sha256. install.sh is unchanged since 0.4.0.