CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.10.2] - 2026-03-13

Added

• Shared bootstrap() function (src/config/bootstrap.ts): Single entry point for configuration initialization — calls loadConfig() → toRuntimeConfig() → initRuntimeConfig(), returns the resolved config, idempotent. Eliminates the recurring pattern where entry points independently chain these calls (or forget to).
• resetRuntimeConfig() in memory-config.ts: Test-only function to clear the runtime config cache.

Changed

• Entry point config initialization: All 4 entry points (src/mcp/server.ts, src/dashboard/server.ts, src/hooks/session-start.ts, src/cli/commands/init/ingest.ts) now use bootstrap() instead of inline initRuntimeConfig(toRuntimeConfig(loadConfig())). The ingest command was also missing initRuntimeConfig() entirely — getConfig() would have returned bare defaults instead of user config.
• SECURITY.md: Updated supported versions to >= 0.10.2.

Tests

• 32 new tests across 3 new/updated test files:
  • test/config/memory-config.test.ts (13 tests): initRuntimeConfig/getConfig cache lifecycle, deep-merge for all 7 nested config objects, override immutability, idempotency.
  • test/config/loader.test.ts (+15 tests): Empty string env vars, NaN handling, clusterHour range validation (−1, 0, 12, 23, 24), halfLifeHours validation (−1, 0, 48), decayFactor validation (−0.1, 0, 0.95).
  • test/config/bootstrap.test.ts (4 tests): Config resolution, idempotency, return value, CLI override passthrough.
• 2589 tests passing.

[0.10.1] - 2026-03-13

Added

• Entity extraction (src/ingest/entity-extractor.ts): Deterministic regex-based extraction of people (@mentions, emails, "X said" patterns), channels (#channels), meetings (standup, retro, 1:1), and URLs from chunk content. Skips code blocks and [Thinking] blocks to reduce noise.
• Entity store (src/storage/entity-store.ts): CRUD layer for entities, aliases, and chunk mentions. Supports alias resolution, re-ingestion safety (INSERT OR IGNORE), and per-entity chunk lookup capped at 100 most recent.
• Entity-aware retrieval: Entity mentions in queries are matched against stored entities and injected as an RRF source (weight 1.5) in both keyword and hybrid search paths. Project-scoped — gracefully skips when no project filter is provided.
• Entity tables (migration v16): Three new tables (entities, entity_aliases, entity_mentions) with cascade deletes and appropriate indexes.
• Entity count in stats: The stats MCP tool now reports entity count.

Changed

• Hybrid retrieval default: retrieval.primary changed from 'keyword' to 'hybrid'. Vector search is now always active at ~14ms cost (local jina-small), which covers narrative/thematic projects without per-project configuration. Backward compatible — retrieval.primary: 'keyword' in config still works.
• Temporal misrouting fix: Updated search and recall tool descriptions to redirect recent/latest session queries to reconstruct. Updated reconstruct description to explicitly claim temporal queries.
• MCP tool descriptions: search now mentions hybrid retrieval and entity boosting; recall and reconstruct include temporal routing guidance.

Fixed

• MCP integration test timeout: Increased beforeAll hook timeout from 10s to 30s to accommodate heavy module imports (ONNX runtime, tree-sitter, LanceDB).

Tests

• 2378 tests passing.

[0.10.0] - 2026-03-12

Added

• Structural repo map (src/repomap/): Tree-sitter-powered codebase analysis that extracts definitions, references, and cross-file relationships. Produces a compact structural summary (~1K tokens) ranked by importance. New repomap MCP tool provides on-demand orientation. 22 languages supported: 12 via tree-sitter (TypeScript, JavaScript, Python, Java, C, C++, Rust, Go, Ruby, C#, PHP, Bash) and 10 via regex fallback (Scala, Kotlin, Swift, Haskell, Lua, Dart, Zig, Elixir, Perl, R). Cached per-file by mtime for fast incremental updates (<100ms). 10 MCP tools total (was 9).
• Session state capture (src/ingest/session-state.ts): Structured extraction of files touched, errors, outcomes, tasks, and optional LLM summary during ingestion. Stored in new session_states table (migration v15).
• Briefing mode for reconstruct: New mode: "briefing" combines session state (files, outcomes, tasks) with the structural repo map for a complete startup context (~2K tokens).
• Summary-augmented recall: The recall tool now searches session summaries by keyword before chain walking. Matching summaries appear as supplementary context alongside chain results, improving answers to "why did we choose X?" queries.
• searchSessionSummaries() in session-state-store: Keyword search over session summaries with stop-word filtering and project scoping.

Changed

• Keyword-first retrieval (default): BM25 keyword search (FTS5) is now the primary retrieval method. Vector search demoted to optional enrichment (vectorEnrichment config toggle, off by default). Cluster expansion only active in hybrid mode.
• Embedding is optional: New embeddingEager config (default: false) — ingestion no longer requires embedding. Chunks are stored with edges and FTS indexing; embedding happens only when explicitly enabled. Reduces startup latency and memory usage.
• Semantic index disabled by default: semanticIndex.enabled changed from true to false. The index entry system remains available as opt-in.
• Lazy query embedding in chain walker: When keyword-primary mode returns no query embedding, the chain assembler embeds the query on demand (single call). Chain walking degrades gracefully when stored embeddings are missing.
• MCP tool descriptions: Updated search (keyword-first), recall (summary-augmented), reconstruct (briefing mode) descriptions.
• Skill templates: Updated recall (summary context), search (keyword-first), resume (briefing mode) skill templates.
• README: Updated architecture diagram, Key Differentiators, MCP tools table, and comparison table to reflect the new approach.
• Config: New fields in MemoryConfig — retrievalPrimary, vectorEnrichment, embeddingEager, repomap. New env vars: CAUSANTIC_RETRIEVAL_PRIMARY, CAUSANTIC_RETRIEVAL_VECTOR_ENRICHMENT, CAUSANTIC_EMBEDDING_EAGER.

Tests

• 2327 tests passing.

[0.9.4] - 2026-03-04

Fixed

• Skill templates missing project scoping: The recall, search, predict, cleanup, and roadmap skill templates now instruct Claude to always pass the project parameter scoped to the current project (derived from the working directory). Previously, these skills could pull in memories from unrelated projects. The resume, reconstruct, and forget skills already required project.

Tests

• 2038 tests passing.

[0.9.3] - 2026-03-04

Fixed

• predict tool documentation: Removed incorrect claim that predict uses half the token budget — it uses the same full mcpMaxResponse budget as search and recall.
• list-sessions missing limit parameter in docs: Added the limit parameter (default 30, added in v0.9.1) to the MCP tools reference.
• retrieval.feedbackWeight undocumented: Added the setting to the retrieval config table — previously only the env var was listed.
• lengthPenalty config section undocumented: Added the lengthPenalty section (enabled, referenceTokens) to the configuration reference.
• Stale version in stats example: Updated from v0.8.0 to current version.

Changed

• future-work.md: Added budget-aware retrieval (v0.9.2) to the "Recently Implemented" section.

Tests

• 2038 tests passing.

[0.9.2] - 2026-03-04

Added

• Budget-aware MMR selection: The MMR greedy selection loop now tracks a running token budget. Candidates that would exceed the remaining budget are excluded from consideration at each step, preventing large chunks from consuming diversity slots when they can't fit in the response. Below the MMR threshold (< 10 candidates), budget filtering still applies.
• Budget-aware chain formatting: Chain output assembly now iterates through chunks in order and only includes those that fit within the remaining token budget. Chunks that would exceed the budget are dropped entirely — no partial chunks are returned. Step numbering adjusts to reflect included chunks only.
• Oversized chunk filtering: Chunks individually larger than the query's maxTokens are now excluded a priori from both search and chain pipelines:
  • Search: Filtered out before MMR reranking so they don't waste diversity slots.
  • Chains: Traversed through for graph connectivity (the chain doesn't break) but excluded from the path output, token count, and median score calculation. Oversized seeds are similarly traversed but not included in chain output.

Changed

• Length penalty token extraction: The chunkTokens variable used for the length penalty is now computed unconditionally (outside the lengthPenalty.enabled guard) and reused for the size filter and MMR budget map, eliminating redundant getChunkById lookups.

[0.9.1] - 2026-03-04

Fixed

• Token budget overhead: Search and reconstruction assemblers now reserve space for formatting overhead (per-chunk headers, separators, response diagnostics) before chunk assembly, preventing responses from exceeding stated token budgets by 5-15%.
• Node version mismatch detection: Hook runner now detects NODE_MODULE_VERSION errors and surfaces actionable guidance ("run: npm install -g causantic") instead of the generic "internal error" message. These errors are also excluded from transient error retries.

Changed

• Skill template memory queries: Roadmap skill reduced from 10 parallel queries at 8K tokens each (80K total) to 4 sequential queries at 4K (16K cap). Cleanup skill reduced from 4 parallel queries at 8K (32K) to 3 sequential queries at 4K (12K cap) with a 2K summarization step before passing to subagents. Both changes address "prompt is too long" failures.
• list-sessions truncation: Added limit parameter (default 30) to the list-sessions MCP tool. When results exceed the limit, displays the most recent sessions with a truncation notice.
• batch-ingest post-run guidance: Output now includes a "Next steps" section recommending npx causantic maintenance run update-clusters to generate topic clusters from ingested sessions.

[0.9.0] - 2026-02-27

Added

• Dashboard retrieval analytics: New analytics section on the Overview page surfaces retrieval feedback data that was previously collected but never visualized. Addresses 4 observability gaps identified in the system audit:
  • Tool call frequency: Horizontal bar chart showing MCP tool usage breakdown (search, recall, predict, etc.)
  • Retrieval volume over time: Weekly time series of retrieval activity, reusing the existing TimeSeries D3 component
  • Top retrieved chunks: Table of the 10 most-retrieved chunks with project, preview, token count, and retrieval count — surfaces dominant-chunk problems
  • Chunk size distribution: Vertical bar chart of chunk token-count buckets (0-200, 201-500, 501-1K, 1K-2K, 2K-5K, 5K+) for validating length penalty tuning
  • Per-project retrieval quality: Projects page now shows Retrievals and Unique Queries columns alongside existing chunk counts
  • Stat cards: Total Retrievals, Unique Queries, and Top Tool summary cards
• ToolUsageChart component (src/dashboard/client/src/components/stats/ToolUsageChart.tsx): D3 horizontal bar chart for tool usage data
• SizeDistribution component (src/dashboard/client/src/components/stats/SizeDistribution.tsx): D3 vertical bar chart for chunk size buckets

Changed

• GET /api/stats: Response now includes an analytics object with toolUsage, retrievalTimeSeries, topChunks, projectRetrievals, sizeDistribution, and totalRetrievals. Gracefully returns empty arrays and 0 when no feedback data exists.
• GET /api/projects: Each project now includes retrievals and uniqueQueries fields (default 0).
• SECURITY.md: Updated supported versions to >= 0.9.0.

Tests

• 4 new route tests: empty analytics, populated analytics with feedback data, zero retrieval counts on projects, per-project retrieval counts.
• 2031 total tests passing.

[0.8.2] - 2026-02-25

Fixed

• Worktree sessions fragment project identity: When Claude Code runs in a worktree (isolation: "worktree", introduced in v2.1.47), hook stdin reports the worktree path (e.g., /tmp/claude-worktree-abc123/) as cwd. Causantic derived project identity from basename(cwd), so worktree sessions were tagged as claude-worktree-abc123 instead of the real project name. All entry points (hook dispatcher, claudemd-generator, session reader, ingestion, hook-utils) now resolve worktree paths back to the main repository via git worktree list --porcelain with a .git file parsing fallback. Project identity is consistent across worktree and non-worktree sessions.

Added

• src/utils/project-path.ts: New utility — resolveCanonicalProjectPath(cwd) detects linked worktrees (.git is a file, not a directory), resolves to the main repo path, and caches results. Uses execFileSync with 500ms timeout, falls back to parsing the .git file. Skips submodules (.git/modules/ paths). Pattern follows device-detector.ts.
• Claude Code Compatibility section in docs/guides/integration.md: Documents worktree resolution, CLAUDE_CODE_SIMPLE mode, enterprise disableAllHooks, and future hook events.

Tests

• 11 new tests in test/utils/project-path.test.ts: normal repo, worktree resolution via git command, .git file fallback, submodule guard, error cases, caching, and a real git worktree integration test.
• Updated test/cli/commands/hook.test.ts and test/parser/session-reader.test.ts with worktree-aware assertions.
• 2066 total tests passing.

[0.8.1] - 2026-02-22

Changed

• Reduced code duplication: Extracted sqlPlaceholders() utility in db.ts (replacing 20 inline occurrences across 9 files) and errorMessage() utility in errors.ts (replacing 20 inline occurrences across 8 files). insertChunk now delegates to insertChunks, createEdge delegates to createEdges. Shared ingestionHookCli() consolidates session-end and pre-compact CLI entry points.
• Dashboard dependency: Bumped lucide-react from ^0.469.0 to ^0.575.0. All 18 icon imports resolve without renames.

Fixed

• 28 documentation accuracy issues across 12 files: storage-api.md edge topology (sequential 1-to-1, not m×n), removed stale hopDecay/linkBoost references, added 3 missing stores. configuration.md gained embedding.model, llm.enableLabelling, clustering.incrementalThreshold, and 5 missing env var mappings. cli-commands.md added reindex command and fixed benchmark categories (chain not graph). traversal-algorithm.md fixed initial_weight (varies by type). integration.md updated hook config format with async: true and added session-end hook. dashboard.md added 4 missing API routes. future-work.md moved implemented items to Recently Implemented. Six other docs received minor accuracy fixes.

Removed

• Stale artifacts: Deleted broken scripts/benchmarks/hdbscan-benchmark.ts (imported non-existent hdbscan-ts dependency, masked by @ts-ignore) and unused test/fixtures/labeled-pairs.json fixture.

[0.8.0] - 2026-02-22

Changed

• Multi-path chain walking: Replaced greedy single-path traversal (walkSingleChain + pickBestEdge) with DFS backtracking (walkAllPaths). At branching points (agent transitions, cross-session links), all paths are now explored and emitted as candidates. selectBestChain() picks the best from a richer candidate set. Linear chains (out-degree 1) produce identical results to the previous algorithm.
• Per-seed independence: Removed global visited set across seeds. Each seed now explores independently with per-path visited sets, allowing different seeds to traverse shared nodes. This produces more candidate chains for selectBestChain() to choose from.
• Agent filter scoping: consecutiveSkips counter is now scoped per recursive frame (passed as parameter), not shared across backtracking paths. Each branch gets its own skip count.

Added

• maxCandidatesPerSeed option on ChainWalkerOptions (default: 10). Caps emitted chains per seed to bound memory usage on highly branched graphs.
• maxExpansionsPerSeed option on ChainWalkerOptions (default: 200). Pre-order counter that bounds total DFS recursive calls per seed, protecting against rare dense subgraphs.
• Score memoization: scoreNode() results are cached per seed walk via Map<string, number>, preventing redundant angularDistance() calls for nodes visited on multiple paths.

Tests

• 10 new multi-path tests (chain-walker-multipath.test.ts): linear chain, branching at root, deep branching, maxDepth emission, expansion budget termination, candidate cap, agent filter with branching, per-seed independence, token budget per-path, orphan seed.
• Updated 2 existing tests for multi-path behavior: shared visited set → per-seed independence, weight-based edge selection → multi-path exploration.
• 2053 total tests passing.

[0.7.2] - 2026-02-22

Changed

• causantic-cleanup skill: Replaced single-agent sequential approach with multi-agent orchestration. Spawns 4 parallel specialist agents (Infrastructure, Design, Documentation, Memory), each with a fresh context window, then synthesizes findings into a prioritised CLEANUP_PLAN.md. Prevents context exhaustion on non-trivial codebases. Includes graceful degradation (falls back to single-agent if specialists fail) and contradiction resolution (when memory contradicts a specialist, both perspectives are preserved with a "Requires human decision" flag).
• CLAUDE.md block: Added /causantic-roadmap to skill listings and Quick Decision Guide.

Added

• causantic-roadmap skill: New skill that gathers candidate work items from multiple sources (CLEANUP_PLAN.md backlog, Causantic memory, codebase TODOs, user-provided goals), deduplicates and classifies them, then organizes into a phased ROADMAP.md (Phase 0-5: Foundation through Aspirational). Designed as a draft for human shaping, not a final plan. Memory-optional — proceeds with available sources if causantic MCP tools are unavailable.

[0.7.1] - 2026-02-21

Fixed

• Agent filter not propagated to chain walking: agentFilter was only applied to seed selection — chain walking followed all edges regardless of agent, causing cross-agent contamination in scoped queries. Now propagated through walkChains() with a maxSkippedConsecutive bound (default 5) to prevent unbounded traversal through non-matching agents.
• Agent filter not propagated to cluster expansion: expandViaClusters() checked project filter but not agent filter. Cluster siblings from other agents leaked into results. Now filters via vectorStore.getChunkAgent().
• Insertion-order edge selection in chain walker: Chain walker picked the first unvisited edge (insertion order) instead of the highest-weight edge. Now uses weight-based selection (initialWeight), improving chain quality.
• Binary recency boost only worked within current session: Chunks from previous sessions received no recency signal at all. Replaced with time-decay boost (1 + decayFactor * exp(-ageHours * ln2 / halfLifeHours)) stacked multiplicatively with 1.2x session boost. Defaults: decayFactor=0.3, halfLifeHours=48. Configurable via recency config section or CAUSANTIC_RECENCY_DECAY_FACTOR / CAUSANTIC_RECENCY_HALF_LIFE_HOURS env vars.
• getChunksBefore returned all agents then post-filtered: SQL query had no agentId parameter, wasting the LIMIT clause. Now filters at SQL level; removed redundant post-filter in session reconstructor.
• Pre-compact exit code for degraded mode: Exited with code 1 (failure) on partial success, signaling hook failure to Claude Code. Now exits with code 0; exit 1 reserved for total failure only.

Added

• Schema v10 migration: Three composite indexes for multi-agent queries — idx_chunks_team_name, idx_chunks_agent_start(agent_id, start_time), idx_chunks_team_start(team_name, start_time).
• VectorStore team index: In-memory chunkTeamIndex with getChunkTeam() accessor, populated during load(), insert(), and insertBatch().

Changed

• Team edge timestamp proximity: Tightened from 30 seconds to 10 seconds. Added log.warn when falling back to timestamp proximity and when multiple chunks match within the window.
• Skill templates: Expanded quick decision guide with 6 missing skills (debug, summary, crossref, retro, cleanup, list-projects). Sharpened recall vs search distinction. Disambiguated reconstruct vs resume entries. Updated proactive memory section (error patterns → debug, added sprint summary and cross-project patterns).
• SECURITY.md: Updated supported versions to >= 0.7.1.

Tests

• 18 new tests (1828 total): chain walker agent filter (4), cluster expander agent filter (2), search assembler time-decay (3), chunk store agentId filter (2), v10 migration indexes (1), vector store team index (2), team edge detector 10s window (2), pre-compact exit codes (2).

[0.7.0] - 2026-02-21

Added

• Agent team support: Full ingestion, retrieval, and output support for Claude Code's multi-agent team sessions (TeamCreate, Task with team_name, SendMessage).
• Team edge types: Three new causal edge types — team-spawn (lead spawns teammate, weight 0.9), team-report (teammate reports back to lead, weight 0.9), peer-message (teammate-to-teammate via SendMessage, weight 0.85).
• Team topology detection (src/ingest/team-detector.ts): Scans main session for TeamCreate/Task/SendMessage signals. Resolves hex agent IDs to human-readable teammate names using a priority chain: Task name param > Task result parsing > SendMessage routing metadata > <teammate-message> XML fallback.
• Team edge detection (src/ingest/team-edge-detector.ts): Matches send/receive events across agent files using <teammate-message> XML tag matching with timestamp proximity fallback (30s in v0.7.0, tightened to 10s in v0.7.1).
• Multi-file teammate grouping: A single teammate can produce multiple subagent files (one per incoming message context). Files are grouped by resolved human name; all chunks receive the same canonical agentId.
• Dead-end file detection: Filters out race-condition stub files created when multiple messages arrive simultaneously at a teammate. Detection uses absence of assistant messages (primary) and ≤2 line count (secondary).
• Agent attribution in output: Search, recall, and reconstruct results now show | Agent: <name> in chunk headers when chunks come from a named agent. Reconstruction shows --- Agent: <name> --- boundary markers.
• agent parameter on MCP tools: search, recall, predict, and reconstruct tools accept an optional agent filter. Filters seed/chunk selection; chain walking still crosses agent boundaries freely.
• Agent team stats: stats tool now reports agent chunk count, distinct agent count, and team edge counts (team-spawn, team-report, peer-message) when present.
• Schema v9 migration: Adds team_name TEXT column to chunks table and idx_chunks_agent_id index.

Changed

• Ingestion pipeline partitioning: Sub-agents are now partitioned into team members (processed through the new team pipeline) and regular sub-agents (existing brief/debrief pipeline). Mixed sessions are handled correctly.
• IngestResult extended: Now includes teamEdges, deadEndFilesSkipped, and isTeamSession fields.
• Skill templates updated: recall, search, predict, reconstruct document the agent parameter. resume and summary include team session guidance.
• CLAUDE.md block: Quick decision guide includes agent filtering note.
• Eslint upgraded to 10.0.1: Resolves 3 minimatch high-severity audit vulnerabilities in eslint's dependency tree. Enabled @typescript-eslint/no-explicit-any as warn for src/ to prevent future any regressions.
• SECURITY.md: Updated supported versions to >= 0.7.

Fixed

• EventEmitter MaxListenersExceeded warning: Fixed listener accumulation in hook command tests by raising process.stdin.setMaxListeners for the test suite scope.

Tests

• Team detector tests (test/ingest/team-detector.test.ts): 21 tests covering detectTeamTopology() (TeamCreate, Task with team_name, SendMessage, progress message resolution, XML fallback) and groupTeammateFiles() (grouping, dead-end filtering, fallback names).
• Team edge detector tests (test/ingest/team-edge-detector.test.ts): 14 tests covering detectTeamEdges() for all three edge types (team-spawn, team-report, peer-message), timestamp proximity fallback, and edge cases.
• Agent filter tests: Added agentId filter tests to chunk-store-time.test.ts (3 tests) and agentFilter/agent boundary marker tests to session-reconstructor.test.ts (4 tests).

[0.6.1] - 2026-02-19

Fixed

• Skill templates not updated in package: The causantic-recall skill template and CLAUDE.md quick decision guide in skill-templates.ts still had the old descriptions. Running causantic init would overwrite the corrected local files with stale templates. Now the package templates match the 0.6.0 routing fixes.

[0.6.0] - 2026-02-19

Fixed

• Chunk ID collisions during incremental ingestion: Chunk IDs used a module-level counter that reset to zero on every process start. When a session was re-ingested after a restart (e.g., via the session-end hook), new chunks for the same session would collide with existing IDs, causing UNIQUE constraint failed: chunks.id errors and silently blocking ingestion. Replaced counter-based IDs with content-addressed SHA-256 hashes (<sessionId>-<hash>) that are deterministic and unique per chunk content. Also changed INSERT to INSERT OR IGNORE in chunk storage as a safety net for idempotent re-ingestion.

Changed

• Skill routing for temporal queries: Updated causantic-recall skill description to explicitly exclude temporal queries ("what did we do last?", "show me recent work"). Added "When NOT to Use" section directing these to reconstruct or resume. Previously, recall's description claimed "recent or past work" as a use case, causing Claude to route temporal queries to semantic search (which has no recency bias) instead of time-ordered reconstruction.
• CLAUDE.md quick decision guide: Added entries for "What were we looking at last?" and "Where did I leave off?" with a bolded note distinguishing semantic tools (recall) from time-ordered tools (reconstruct/resume).

[0.5.6] - 2026-02-19

Added

• Timeline mode for reconstruct: Call reconstruct with just project (no time range parameters) to get the most recent history up to the token budget. Walks backward from now (or a to anchor) using an efficient SQL query. No need to specify from, days_back, session_id, or previous_session for simple "show me recent work" queries.

Changed

• reconstruct tool description: Updated to document timeline mode as the default behavior when called with just project.
• causantic-reconstruct skill: Added no-argument usage (timeline mode) and updated intent table.
• CLAUDE.md block: Updated reconstruct description and quick decision guide to include "What happened recently?" intent.

[0.5.5] - 2026-02-19

Fixed

• Init wizard skipping stale MCP server paths: Fixed causantic init skipping over stale MCP server paths during setup.

[0.5.4] - 2026-02-18

Changed

• MMR reranking: Added Maximal Marginal Relevance (MMR) diversity reranking to search results. Removed redundant cluster boostFactor.
• Dashboard search labels: Updated dashboard search labels to reflect MMR reranking.

[0.5.3] - 2026-02-17

Changed

• Expanded Prettier formatting scope: Formatted 79 previously unformatted files (dashboard client, scripts, config, docs). Expanded format:check to cover dashboard .tsx/.css, scripts, and config files.
• Bumped @typescript-eslint from 8.55.0 to 8.56.0 (patch release).

Fixed

• Stale MCP tool references in docs: quick-start.md referenced non-existent explain tool — corrected to search, recall, and predict. integration.md had a 3-tool stub table — replaced with complete 9-tool table.

Removed

• Unused filterAlreadyIngested() export: No-op function in batch-ingest.ts, never called outside its barrel export.

Added

• CLI command handler tests: 35 new tests for hook, ingest/batch-ingest, and export/import command handlers (1742 total tests).

[0.5.2] - 2026-02-16

Changed

• Claude Code 5.1+ minimum: Documented Claude Code 5.1+ as a prerequisite. The async hook support added in v0.5.1 requires it.
• Removed prepublishOnly script: Build and test are handled by CI, not by npm lifecycle hooks.

[0.5.1] - 2026-02-16

Changed

• Async hooks: PreCompact and both SessionEnd hooks now run with async: true (fire-and-forget), so they no longer block Claude Code sessions. SessionStart remains synchronous since its stdout delivers memory context.
• Hook dedup logic: causantic init now compares full hook objects (not just command strings), so existing installs pick up the async flag on re-init.

Fixed

• N+1 cluster query in SessionStart: Replaced per-cluster loop (getClusterChunkIds + getChunksByIds × N clusters) with a single batch SQL query (getClusterProjectRelevance). 50 clusters now costs 1 query instead of 100+.
• SessionStart loads all chunks to slice last N: New getRecentChunksBySessionSlug() uses SQL ORDER BY ... DESC LIMIT instead of loading every chunk then slicing in JS.
• SessionStart loads all clusters then filters: New getClustersWithDescriptions() uses SQL WHERE description IS NOT NULL instead of loading all clusters then filtering in JS.

[0.5.0] - 2026-02-16

Fixed

• MCP config written to wrong file: causantic init was writing MCP server configuration to ~/.claude/settings.json, but Claude Code reads MCP servers from ~/.claude.json. MCP config now writes to ~/.claude.json; hooks remain in settings.json. Includes automatic migration of existing entries from settings.json to ~/.claude.json on re-init.
• Uninstall cleanup: causantic uninstall now removes MCP entries from both ~/.claude.json (current) and ~/.claude/settings.json (legacy).

[0.4.3] - 2026-02-15

Fixed

• MCP server notification handling: Server now silently ignores JSON-RPC notifications (e.g. notifications/initialized) instead of returning METHOD_NOT_FOUND errors, which caused Claude Code to fail loading the MCP server

Changed

• Reference docs: Synced docs/reference/skills.md descriptions with README and updated version in docs/reference/mcp-tools.md

[0.4.2] - 2026-02-15

Changed

• README: Clarified that Anthropic API key is optional (only used for cluster topic labeling via Haiku); all core retrieval works without it
• Skill descriptions: Sharpened all skill descriptions in README and CLAUDE.md block to clearly differentiate each tool — recall (backward chain walk), predict (forward chain walk), reconstruct (replay), summary (recap), retro (patterns)

[0.4.1] - 2026-02-15

Added

• CLI commands reference in CLAUDE.md block: Claude Code now knows all 16 CLI commands without needing to run causantic --help. Eliminates repeated help lookups during sessions.

Fixed

• README Key Differentiators numbering (duplicate "5." corrected to "4." and "5.")
• SECURITY.md supported versions updated to v0.4.x only

[0.4.0] - 2026-02-15

Changed

• Episodic Retrieval Pipeline: Redesigned recall/predict from graph traversal to chain walking. Seeds found by semantic search; the causal graph unfolds them into ordered narrative chains; chains ranked by aggregate semantic relevance per token.
• Sequential edge structure: Replaced m×n all-pairs edges with sequential linked-list (intra-turn C1→C2→C3, inter-turn last→first, cross-session last→first). All edges stored as single forward rows with uniform weight.
• MCP tools: Replaced explain with search (semantic discovery). recall and predict now return episodic chain narratives with search-style fallback. Added hook-status, stats, and forget tools. MCP server now exposes 9 tools.
• Benchmark scoring: Replaced Graph Value (30%) with Chain Quality (25%). Updated weights: Health 25%, Retrieval 35%, Chain 25%, Latency 15%.
• Schema v8: Added composite indices on edges for directional chain walking queries.
• Skills: Merged /causantic-context into /causantic-explain (dual-purpose: "why" questions + area briefings). Rewrote /causantic-crossref for explicit cross-project search (discovers projects → per-project filtered search → comparison). Added /causantic-status, /causantic-summary, and /causantic-forget. 14 skills total.
• Hook consolidation: Extracted shared handleIngestionHook() in hook-utils.ts from near-identical session-end.ts and pre-compact.ts.
• SessionStart error context: Fallback message now includes a classified error hint (database busy, database not found, embedder unavailable, internal error) instead of a generic static string.

Added

• /causantic-forget skill: Guided memory deletion by topic, time range, or session with dry-run preview and confirmation workflow.
• Skills reference documentation (docs/reference/skills.md): Reference page for all 14 skills with parameters, usage examples, and decision guide.
• Semantic deletion for forget tool: Added query and threshold parameters for topic-based deletion (e.g., "forget everything about authentication"). Uses vector-only search for precision. Dry-run shows top matches with similarity scores and score distribution. Combinable with time/session filters via AND logic.
• search MCP tool: Pure semantic discovery — vector + keyword + RRF + cluster expansion.
• hook-status MCP tool: Shows when each hook last ran and whether it succeeded. Use for diagnosing hook firing issues.
• stats MCP tool: Memory statistics — version, chunk/edge/cluster counts, per-project breakdowns.
• forget MCP tool: Delete chunks by project, time range, or session. Requires project slug. Defaults to dry-run preview. Cascades to edges, clusters, FTS, and vectors.
• Chain walk diagnostics: recall and predict append a diagnostic bracket on fallback explaining why the chain walker fell back to search (no chunks, no seeds, no edges, short chains, or threshold not met).
• Chain walker (src/retrieval/chain-walker.ts): Follows directed edges to build ordered narrative chains with token budgeting and cosine-similarity scoring.
• Chain assembler (src/retrieval/chain-assembler.ts): Seeds → chain walk → rank → best chain or search fallback.
• Search assembler (src/retrieval/search-assembler.ts): Pure search pipeline extracted from context assembler.
• Chain quality benchmarks: Measures chain coverage, mean chain length, score per token, fallback rate.
• Edge rebuild command: npx causantic maintenance rebuild-edges — rebuilds edges using sequential linked-list structure without re-parsing or re-embedding.
• claudemd-generator wired to SessionEnd: The hook now runs automatically after session ingestion, keeping CLAUDE.md up to date.
• /causantic-status skill: Calls hook-status + stats MCP tools, presents combined health report.
• /causantic-summary skill: Summarize recent work across sessions — list-sessions → reconstruct → synthesize accomplishments/in-progress/patterns.
• Dashboard Timeline page: Replaced force-directed graph with D3 horizontal swimlane timeline, chunk inspector, and chain walk viewer.
• Dashboard chain walk route: GET /api/chain/walk — structural chain walk from a seed chunk for dashboard display.
• Dashboard timeline route: GET /api/timeline — chunks ordered by time with edges for arc rendering.
• Removed skill cleanup: causantic init now deletes directories for removed skills (e.g., causantic-context) on re-init.

Removed

• explain MCP tool: Subsumed by recall (both walk backward).
• /causantic-context skill: Merged into /causantic-explain, which now handles both "why" questions and area briefings.
• Sum-product traverser: Replaced by chain walker. Deleted src/retrieval/traverser.ts.
• Hop-based decay: Deleted src/storage/decay.ts. Chain scoring uses direct cosine similarity instead.
• Graph-value benchmarks: Replaced by chain-quality benchmarks. Deleted src/eval/collection-benchmark/graph-value.ts.
• Config: decay section: Removed entirely from ExternalConfig and config.schema.json.
• Config: traversal.minWeight: No longer needed (chain walker uses token budget, not weight-based pruning).
• Config: hybridSearch.graphWeight: Graph traversal no longer participates in RRF fusion.
• Dashboard: Deleted ForceGraph.tsx, DecayCurves.tsx, GraphExplorer.tsx — replaced by Timeline page.

[0.3.6] - 2026-02-15

Fixed

• MCP error messages: Tool failure responses now include the actual error message instead of generic "Tool execution failed", making transient errors diagnosable without opt-in stderr logging.

Changed

• CI formatting enforcement: Added format:check step to CI workflow so formatting drift is caught before merge.
• Circular dependencies resolved: Extracted shared types into src/maintenance/types.ts and src/dashboard/client/src/lib/constants.ts to break 5 circular dependency cycles.

Housekeeping

• Fixed 5 ESLint warnings (consistent-type-imports, unused imports).
• Bumped typedoc 0.28.16 → 0.28.17 (fixes moderate ReDoS in markdown-it).
• Synced package-lock.json.
• Ran prettier on 19 files with formatting drift.
• Archived stale documentation for removed vector clock and decay systems.

[0.3.0] - 2026-02-12

Changed

• Time-based edge decay: Replaced vector-clock hop counting with intrinsic time-based edge decay. Each edge's weight decays based on its age (milliseconds since creation), not logical hops. Backward edges use delayed-linear (60-minute hold), forward edges use exponential (10-minute half-life).
• Broadened vector TTL: cleanupExpired() now applies to ALL vectors, not just orphaned ones. Vectors older than the TTL (default 90 days) are cleaned up regardless of edge status.
• Simplified traversal: traverse() and traverseMultiple() use time-based decay configs directly. Sum-product rules unchanged.

Added

• FIFO vector cap: New vectors.maxCount config option evicts oldest vectors when the collection exceeds the limit. Default: 0 (unlimited).

Removed

• Vector clocks: Clock store, clock compactor, and vector-clock module deleted. Vector clock columns dropped from SQLite schema (v7 migration).
• Graph pruner: prune-graph maintenance task removed. Edge cleanup happens via FK CASCADE when chunks are deleted by TTL/FIFO. Maintenance tasks reduced from 5 to 4.
• Orphan lifecycle: Chunks no longer transition through an "orphaned" state. They go directly from active to expired when TTL elapses.

[0.2.1] - 2026-02-11

Added

• SessionEnd hook: Triggers session ingestion on /clear, logout, and exit — closes the gap where chunks were lost between compaction events
• Shared ingestCurrentSession() helper extracted from PreCompact, used by both PreCompact and SessionEnd hooks
• Dynamic hook name logging in causantic init

[0.2.0] - 2026-02-11

Added

• Schema v6: Session Reconstruction: Pure chronological SQLite queries for "what did I work on?" — composite index on (session_slug, start_time), MCP tools list-sessions and reconstruct
• Project-Filtered Retrieval: Federated approach with projectFilter on retrieval requests, cross-project graph traversal preserved
• Collection Benchmark Suite: Self-service benchmarks for health, retrieval quality, graph value, and latency with scoring, tuning recommendations, and history tracking
• Web Dashboard: React + Vite frontend with D3.js visualization — 5 pages (Overview, Search, Timeline, Clusters, Projects), 10 API routes
• CLAUDE.md Generator Hook: Automatic memory context injection into project CLAUDE.md
• Hybrid BM25 + Vector Search: Full-text keyword search via SQLite FTS5 with porter stemming, fused with vector search using Reciprocal Rank Fusion (RRF)
• Cluster-Guided Expansion: Retrieval results expanded through HDBSCAN cluster siblings, surfacing topically related chunks
• Source Attribution: Returned chunks tagged with retrieval source (vector, keyword, cluster, graph)
• Graph Agreement Boost: Vector+graph score fusion — when both pipelines agree on a chunk, its score is boosted; graphBoostedCount metric added to benchmarks
• Post-HDBSCAN Noise Reassignment: Noise points reassigned to nearest cluster via centroid distance, improving cluster coverage
• 6 MCP Tools (v0.2.0): recall, explain, predict, list-projects, list-sessions, reconstruct (Note: explain was later replaced by search; hook-status, stats, and forget added in v0.4.0)
• Schema v5 Migration: FTS5 virtual table with automatic sync triggers; graceful fallback when FTS5 is unavailable
• Initial open source release
• Core memory ingestion and storage system
• Native TypeScript HDBSCAN clustering
• Claude Code hook integration (session-start, pre-compact, claudemd-generator)
• Graph-based retrieval with hop-based temporal decay
• Time-based edge decay for temporal weighting
• Configuration system with JSON schema validation
• Per-chunk encryption (ChaCha20-Poly1305, key stored in system keychain)

Changed

• HDBSCAN rewrite: Pure TypeScript implementation replacing hdbscan-ts — 130× speedup (65 min → 30 sec for 6,000 points)
• Direction-specific decay: Backward and forward edges use different decay curves (empirically tuned)
• MCP tools: Expanded from 3 to 6 tools (added list-projects, list-sessions, reconstruct)
• Clustering threshold: Tuned default from 0.09 → 0.10

Fixed

• README config example: corrected stale clustering.threshold default value

Infrastructure

• Utility deduplication and standardized logging
• ESLint no-console rule for consistent log handling
• Test coverage: 1,684 tests passing in vitest

Research Findings

• Topic continuity detection: 0.998 AUC
• Clustering threshold optimization: F1=0.940 at 0.09
• Graph traversal experiment: 4.65× context augmentation (v0.2 sum-product; replaced by chain walking in v0.4.0)
• Embedding model selection: jina-small for optimal size/quality tradeoff
• Direction-specific decay: backward (dies@10 hops) vs forward (5-hop hold, dies@20)

[0.1.0] - 2026-02-08

Added

• Initial release
• Session parsing and chunking
• Embedding generation with jina-small
• SQLite storage for chunks and edges
• LanceDB vector store
• Basic graph traversal
• HDBSCAN clustering integration
• MCP server prototype