From 9f8abf023fddaa444cb792f3df13a1b37e759e0a Mon Sep 17 00:00:00 2001 From: Greg von Nessi Date: Wed, 4 Mar 2026 14:25:27 +0000 Subject: [PATCH] Bump v0.9.3: fix doc inaccuracies and gaps - Remove incorrect predict half-budget claim - Add missing list-sessions limit parameter - Document retrieval.feedbackWeight and lengthPenalty config sections - Update stats example version, future-work recently implemented --- CHANGELOG.md | 18 ++++++++++++++++++ docs/reference/configuration.md | 14 +++++++++++++- docs/reference/mcp-tools.md | 5 +++-- docs/research/future-work.md | 1 + package.json | 2 +- 5 files changed, 36 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ec0178c..df5985c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [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 diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index dd89e93..469646a 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -81,6 +81,17 @@ Controls cluster-guided expansion during retrieval. These settings are internal | `maxClusters` | `integer` | `3` | Maximum clusters to expand from per query | | `maxSiblings` | `integer` | `5` | Maximum sibling chunks added per cluster | +## Length Penalty Settings + +### `lengthPenalty` + +Controls logarithmic length penalty for large chunks in search results, preventing keyword-rich chunks from dominating. + +| Property | Type | Default | Description | +| ----------------- | --------- | ------- | ------------------------------------------------------------------ | +| `enabled` | `boolean` | `true` | Enable length penalty in search scoring | +| `referenceTokens` | `integer` | `500` | Reference token count for the logarithmic penalty. Chunks above this size receive diminishing scores. | + ## Recency Settings ### `recency` @@ -107,7 +118,8 @@ Controls the search retrieval pipeline. | Property | Type | Default | Description | | ----------- | -------- | ------- | ------------------------------------------------------------------ | -| `mmrLambda` | `number` | `0.7` | MMR (Maximal Marginal Relevance) lambda parameter (0-1) | +| `mmrLambda` | `number` | `0.7` | MMR (Maximal Marginal Relevance) lambda parameter (0-1) | +| `feedbackWeight` | `number` | `0.1` | Weight applied to implicit relevance feedback signals (0-1) | MMR reranks search results to balance relevance with diversity. After RRF fusion and cluster expansion, candidates are reordered so that semantically redundant chunks yield to novel ones. diff --git a/docs/reference/mcp-tools.md b/docs/reference/mcp-tools.md index 9b5d076..e3e846a 100644 --- a/docs/reference/mcp-tools.md +++ b/docs/reference/mcp-tools.md @@ -80,7 +80,7 @@ Predict what context or topics might be relevant based on current discussion. Wa | `project` | `string` | No | Filter to a specific project. Omit to search all. Use `list-projects` to see available projects. | | `agent` | `string` | No | Filter to a specific agent (e.g., `"researcher"`). Applies to seed selection; chain walking crosses agent boundaries. | -**Response**: Plain text. Returns `"Potentially relevant context (N items):"` followed by assembled text, or `"No predictions available based on current context."` if no matches. Uses half the token budget of recall/search. Includes chain walk diagnostics when falling back to search. +**Response**: Plain text. Returns `"Potentially relevant context (N items):"` followed by assembled text, or `"No predictions available based on current context."` if no matches. Includes chain walk diagnostics when falling back to search. ### list-projects @@ -112,6 +112,7 @@ List sessions for a project with chunk counts, time ranges, and token totals. Us | `from` | `string` | No | Start date filter (ISO 8601). | | `to` | `string` | No | End date filter (ISO 8601). | | `days_back` | `number` | No | Look back N days from now. Alternative to `from`/`to`. | +| `limit` | `number` | No | Maximum sessions to display (default: 30). Most recent shown when truncated. | **Response**: Plain text list of sessions with abbreviated IDs, timestamps, chunk counts, and token totals. @@ -170,7 +171,7 @@ Show memory statistics including version, chunk/edge/cluster counts, and per-pro **Example**: ``` -Causantic v0.8.0 +Causantic v0.9.3 Memory Statistics: - Chunks: 1234 diff --git a/docs/research/future-work.md b/docs/research/future-work.md index 5606ab9..a69bd6e 100644 --- a/docs/research/future-work.md +++ b/docs/research/future-work.md @@ -18,6 +18,7 @@ These items were previously listed as future work and have since been implemente - **MMR Reranking** (v0.5.4): Maximal Marginal Relevance reranking in the search pipeline. Single `retrieval.mmrLambda` knob (default 0.7) controls relevance vs diversity. Cluster `boostFactor` removed — redundant with MMR. - **Multiple Embedding Models** (v0.7.0): Configurable via `embedding.model` (jina-small, nomic-v1.5, jina-code, bge-small). Changing model requires `npx causantic reindex` to re-embed all chunks. Model-specific clustering thresholds handled via calibration. - **Multi-Path Chain Walking** (v0.8.0): DFS with backtracking explores all paths from seed chunks, emitting each as a candidate chain. `selectBestChain()` picks the winner by highest median per-node cosine similarity. Bounded by `maxExpansionsPerSeed` (200) and `maxCandidatesPerSeed` (10). For linear chains, behavior identical to previous greedy single-path. +- **Budget-Aware Retrieval** (v0.9.2): Token budget enforcement at multiple pipeline stages — oversized chunk filtering (pre-MMR and chain passthrough), budget-aware MMR selection (greedy loop tracks remaining budget), and budget-aware chain formatting (drop chunks exceeding remaining budget, no partial chunks). ## High Priority diff --git a/package.json b/package.json index 456f997..1d9f362 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "causantic", - "version": "0.9.2", + "version": "0.9.3", "description": "Long-term memory for Claude Code — local-first, graph-augmented, self-benchmarking", "type": "module", "private": false,