nexusmem 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -9,6 +9,61 @@ built from, matched by publish timestamp: `v0.1.0` → `67a4776`, `v0.1.1` → `
 
 ## [Unreleased]
 
+## [0.3.0] — 2026-08-13
+
+**Upgrade note.** The first `sync` after upgrading drops every stored embedding and rebuilds it.
+This is not optional and it is not a bug: embeddings now come from Ollama's `/api/embed`, which
+returns L2-normalised vectors, while the previous `/api/embeddings` did not — measured norms of 1.0
+and 20.7 for the same input. `nodes_vec` ranks by Euclidean distance and records no per-row
+provenance, so a corpus holding both would separate by scale rather than by meaning. `sync` says
+what it dropped, nodes are untouched, and BM25 keeps working while the rebuild runs. On this repo
+the rebuild was 833 nodes in one pass, inside a 9-second sync.
+
+### Added
+
+- **Session summaries via a local model** (`sources.session`, opt-in, off by default). Each
+  finished session becomes one distilled `session_summary` node — decisions and their reasons —
+  alongside the raw exchanges. Runs a local Ollama chat model (`qwen2.5:3b` by default); nothing is
+  downloaded automatically and no transcript leaves the machine. New `scan-session` command, with
+  `--dry-run` to print the exact prompt a session would produce without calling the model.
+  Bounded three ways: a session must be quiet for `settleMinutes` (default 30) before it is
+  eligible, the prompt is hashed so an unchanged session never reaches the model again, and
+  `maxSessions` caps how many are summarized per sync. Every exchange is redacted before the model
+  sees it, and the model's own output is redacted again before it is stored.
+- **`sync --embed-limit <n>`** to cap the embedding pass, for when draining the whole backlog is not
+  wanted.
+
+### Changed
+
+- **The embedding pass drains the backlog in one `sync`** instead of stopping after 200 nodes, and
+  sends texts to Ollama in batches of 32 — measured at 4.21x the throughput of one call per node
+  (20.3ms → 4.8ms per node, over 96 real nodes from this repo). Leaving it uncapped is safe because
+  paging walks rowids monotonically, so a node the provider failed on is passed over rather than
+  retried forever, and because three consecutive dead requests end the pass: an Ollama that is not
+  running now costs three requests rather than one timeout per node.
+- **Embeddings carry a provider identity.** Changing the embedding model, or upgrading from a
+  release that recorded no identity, drops the vectors and re-embeds rather than ranking across a
+  mixture.
+- **Ranking priors now share one budget instead of getting one each.** `signal` and `recency` are
+  query-independent, and each was separately capped at overturning a 2× relevance gap. The score
+  multiplies them, so together they could overturn 4× — which is not a corner case but a description
+  of every commit made during an active working day, fresh and high-signal at once. A query about the
+  PowerShell hook returned two unrelated same-day `fix:` commits at ranks 3 and 4 while the section
+  that answered it sat at rank 6. The 2× budget is now the bound on the priors *jointly*, split
+  between them (`signal^0.215 × recency^0.288`, down from `^0.431` and `^0.576`), and a third prior
+  would re-divide the same budget rather than enlarge it. Measured on four real queries against this
+  repository's memory: the answering section rose in three of them — the rationale for "why BM25
+  before vector search" went from rank 4 to rank 1 — and no query's correct top hit was displaced.
+
+### Known limitation
+
+- Session-summary *titles* depend on the model following a fixed output format, and a 3B model often
+  does not. Measured over 14 real sessions, roughly a third came back usable; the rest were
+  conversational preambles, stray bullets, or a bare "Summary of the Session". Those are rejected
+  and the title falls back to the first line of the question that opened the session — always
+  specific, not always elegant. Compliance was worst on long sessions and on transcripts not in
+  English. `sources.session.model` takes a larger model if it matters.
+
 ## [0.2.0] — 2026-08-12
 
 **Upgrade note.** Both new sources are on by default, so the first `sync` after upgrading an
@@ -119,7 +174,8 @@ First public release.
   there is no local-model summarization pass, and the conversation collector has never been audited
   for the stale-node bug that was found and fixed in the docs collector.
 
-[Unreleased]: https://github.com/yaminbakoh4-dot/NexusMem/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/yaminbakoh4-dot/NexusMem/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/yaminbakoh4-dot/NexusMem/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/yaminbakoh4-dot/NexusMem/compare/v0.1.2...v0.2.0
 [0.1.2]: https://github.com/yaminbakoh4-dot/NexusMem/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/yaminbakoh4-dot/NexusMem/compare/v0.1.0...v0.1.1

package/README.md

@@ -4,6 +4,8 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-informational)](LICENSE)
 ![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen)
 
+![NexusMem: init, sync, status, and a query against this repo's own history](docs/demo.gif)
+
 Your coding agent can read `git log`. It cannot read the four things you tried last Tuesday that
 didn't work.
 
@@ -42,7 +44,9 @@ Relevant history for: windows spawn failure
 ```
 
 A commit and a docs section, ranked against each other, inside whatever token budget you gave it.
-Nothing was summarized by a model on the way out; the ranker just decided what not to send.
+Nothing was summarized by a model on the way out; the ranker just decided what not to send. (One
+optional source, session summaries, does run a local model — but at ingest time, never on the way
+out. What you query is always stored text.)
 
 For a sense of what actually accumulates, here is `nexusmem status` on this repo after two days:
 
@@ -79,7 +83,7 @@ they agree on. No hand-tuned normalization constant sits between them.
 Ranking then multiplies three factors:
 
 ```
-score = relevance × signal^0.431 × recency^0.576
+score = relevance × signal^0.215 × recency^0.288
 ```
 
 `relevance` comes from the query. `signal` (a `fix:` commit outranks a `chore:`; a command that
@@ -89,13 +93,50 @@ zero out a strong match.
 
 Those exponents are derived, not tuned. Priors kept overturning the query: on one real query a `fix:`
 commit took rank 1 from a better-matching docs section on a 44% signal edge against a 15% relevance
-deficit. So each prior is raised to the power that caps its entire range at overturning a 2× relevance
-gap, by solving `span^exponent = 2`. Priors still order equally-relevant hits exactly as before, since
-the transform is monotonic. They just cannot outvote the question anymore.
+deficit. So the priors get a **shared** budget — across their whole range they may overturn at most a
+2× relevance gap — split evenly between them, and each is raised to the power that makes its own span
+worth exactly its share (`span^exponent = √2`). Priors still order equally-relevant hits exactly as
+before, since the transform is monotonic. They just cannot outvote the question anymore.
+
+The budget is shared rather than per-prior for a reason found by dogfooding, not by reading the
+arithmetic: the score *multiplies* the priors, so capping each at 2× separately left the pair free to
+overturn 4×. That describes every commit made during an active working day — fresh and high-signal at
+once — so the failure landed on precisely the days with the most worth remembering. A query about the
+PowerShell hook returned two unrelated same-day `fix:` commits at ranks 3 and 4 while the section that
+answered it sat at rank 6. Adding a third prior now re-divides the same budget instead of enlarging it.
 
 Without Ollama, vector search is skipped and you get BM25 only. That path is fully supported, not a
 degraded error state; `sync` and `query` both succeed and simply do less.
 
+## Session summaries (optional, local model)
+
+With `sources.session.enabled`, each finished session becomes one distilled node next to the raw
+exchanges — what was decided and why, rather than forty individual turns. It runs a local Ollama
+chat model (`qwen2.5:3b` by default); nothing is downloaded automatically and nothing leaves the
+machine.
+
+```bash
+nexusmem scan-session --dry-run
+```
+
+That prints the exact prompt a session would produce, after redaction and budget trimming, without
+calling the model.
+
+Three things bound the cost. A session is only summarized once it has been quiet for
+`settleMinutes` (default 30), so a session in progress is not re-summarized on every sync. The
+prompt is hashed, and an unchanged hash skips the model entirely — on this repo a steady-state sync
+of 14 summarized sessions takes 0.25s and makes no model calls. And `maxSessions` (default 10) caps
+how many reach the model per run; the rest are reported as queued and picked up next sync.
+
+**What it is actually like, measured on 14 real sessions with `qwen2.5:3b`.** The summaries
+themselves are good: decisions with their reasons, in the shape the prompt asks for. Titles are less
+reliable — the model returned a usable one about a third of the time, and otherwise produced a
+conversational preamble, a stray bullet, or a bare "Summary of the Session". Those are rejected and
+the title falls back to the first line of the question that opened the session, which is always
+specific even when it is not elegant. Compliance was worst on long sessions and on transcripts not
+in English. A larger model (`qwen2.5:7b`) is the lever if the titles matter to you; set
+`sources.session.model`.
+
 ## Use it from an agent
 
 ```json
@@ -177,7 +218,13 @@ optimizing, and it is somebody else's process.
   at the prompt is not reconstructed.
 - **Scrape-fallback ids drift** if the history file is trimmed from the front between syncs.
   Installing the hook fixes this.
-- **The embedding pass is capped per `sync`**, so a large corpus needs a few runs to embed fully.
+- **Session-summary titles depend on the model following instructions**, and a 3B model often does
+  not. The fallback keeps them specific rather than generic, but see the section above for what to
+  expect.
+- **Changing the embedding model re-embeds everything.** Vectors from two models are not comparable
+  and `nodes_vec` records no per-row provenance, so `sync` drops the lot and rebuilds rather than
+  ranking across a mixture. It says so when it happens. Nodes are untouched and BM25 keeps working
+  throughout.
 - **Diff indexing is bounded, and deliberately lossy.** A first sync indexes the patches of the most
   recent 200 commits (later syncs only walk `cursor..HEAD`); merge commits contribute none, since
   their patch exists only in a combined format this parser does not read; and binaries, lockfiles and
@@ -194,12 +241,13 @@ optimizing, and it is somebody else's process.
   unmounted drive is not a deleted project.
 - **Conversation chunking is unevaluated.** Splitting long replies at heading boundaries measurably
   helped, but it has never been tested systematically.
-- **A burst of recent, high-signal commits crowds unrelated queries.** Each prior is individually
-  capped at overturning a 2× relevance gap, but the caps are per-prior, not joint, so a node that is
-  both very fresh and highly scored can overturn roughly 4×. Found by dogfooding: a query about the
-  PowerShell hook returned two same-day `fix:` commits with nothing to do with it at ranks 3 and 4,
-  while the section that actually answered the question sat at rank 6. Gets worse on days with a lot
-  of commits, which are exactly the days you have most to remember.
+- **The size of the prior budget is a judgement call, not a measured optimum.** Priors are now
+  bounded jointly rather than one at a time, which closed a real 4× hole (see the ranking section),
+  but the 2× budget itself has never been tuned against a labelled relevance set — there isn't one.
+  It is a defensible constant, not a result. What is measured is the direction: on four real queries
+  against this repo's own memory, switching to the joint cap moved the section that answered the
+  question up in three of them (the rationale section for "why BM25 before vector search" went from
+  rank 4 to rank 1) and displaced no query's correct top hit.
 
 ## Commands
 
@@ -267,11 +315,8 @@ Deleting `.nexusmem/` loses nothing that `sync` cannot rebuild.
 
 ## Status
 
-Ingestion, hybrid retrieval, budgeted packing and the MCP server all work and are covered by 265
-tests running on Linux and Windows across Node 22 and 24.
-
-Not done yet: there is no local-model summarization pass, and the embedding pass is still capped per
-`sync`.
+Ingestion, hybrid retrieval, budgeted packing and the MCP server all work and are covered by 315
+tests running on Linux and Windows across Node 22 and 24. Phase 3 is complete.
 
 ## Development