Bump v0.9.3: fix doc inaccuracies and gaps

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

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.
 

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

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
 

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,