nexusmem 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -9,6 +9,59 @@ built from, matched by publish timestamp: `v0.1.0` → `67a4776`, `v0.1.1` → `
 
 ## [Unreleased]
 
+No unreleased changes yet.
+
+## [0.8.0] — 2026-08-22
+
+### Added
+
+- Provenance widened from 2 tiers to a 4-tier trust hierarchy: `observed` (commits, diffs, shell
+  exit codes) > `authored` (doc sections — human-written claims) > `recorded` (conversation turns —
+  verbatim discourse) > `derived` (session summaries — a model's distillation). Schema V7 backfills
+  existing databases by kind. The ranker decays each tier at its own rate (lower trust fades
+  faster); the ordering is the design claim, the exact ratios are documented judgment calls.
+- Contradiction checking now runs automatically during `sync`: at most 3 new SLM judgments per run
+  (`contradictions.maxPerSync`; `contradictions.autoCheck: false` turns it off), gated on the
+  embedding provider already being reachable. Every judgment — either verdict — is memoized in a new
+  `contradiction_checks` table (schema V8), so a judged pair is never sent to the model again and
+  repeat syncs converge to zero model calls. Measured live against this repo's own database: 5.4s
+  for the first 10 judgments, 0.5s for the identical re-run. Still suggest-only: nothing ever writes
+  `supersedes` automatically.
+- Standing suggestions now surface everywhere without a model in the loop: plain `nexusmem stale`
+  decorates flagged candidates from the memoized judgments (instant, offline), `nexusmem status`
+  gains a `flagged` line, and the sync summary reports new/open suggestion counts.
+- `stale --check-contradictions` reuses each candidate's stored embedding instead of re-embedding
+  it, and stops after two consecutive null SLM replies so a down provider costs at most two timeouts
+  rather than one per candidate.
+
+## [0.7.0] — 2026-08-21
+
+### Added
+
+- `nexusmem stale --check-contradictions`: for each stale candidate, finds the most similar newer
+  node (local embedding search) and asks a local SLM (Ollama, `qwen2.5:3b` by default) whether it
+  actually contradicts the older one, instead of only surfacing by age. Suggest-only — nothing is
+  written, same as plain `stale`. Live-dogfooded against this repo's own real database and Ollama
+  instance; found and fixed a real gap along the way (below) before the feature surfaced anything
+  useful.
+- Import graph: bare Python imports with no leading dot (`import foo`, `from foo import bar`)
+  now resolve to a same-directory sibling file too, alongside the existing relative-dot support.
+  Found dogfooding two real local projects: neither used a single PEP 328 relative import, both
+  relied entirely on this flat-script style. Guarded by a static list of stdlib module names so a
+  bare `import os`/`import queue`/etc. is never mistaken for a same-named local file.
+
+### Fixed
+
+- Import graph: a Java wildcard import (`import a.b.*;`) no longer merges files from two
+  unrelated packages that happen to share a directory-name suffix (e.g. two Gradle/Maven modules
+  each with their own `.../foo`) — it now refuses to guess, same as the single-class-import case.
+- `stale --check-contradictions`'s neighbor search now looks past same-timestamp sibling nodes
+  (e.g. the many chunks one long conversation gets split into) to reach genuinely newer content.
+  Found live-dogfooding against this repo's own database: the first real candidate's closest 15
+  neighbors were all same-conversation siblings sharing its exact timestamp, so the original
+  5-neighbor default silently found zero suggestions for every candidate, regardless of what the
+  SLM would have said.
+
 ## [0.6.0] — 2026-08-20
 
 ### Added
@@ -451,7 +504,9 @@ 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/yaminbkk/NexusMem/compare/v0.6.0...HEAD
+[Unreleased]: https://github.com/yaminbkk/NexusMem/compare/v0.8.0...HEAD
+[0.8.0]: https://github.com/yaminbkk/NexusMem/compare/v0.7.0...v0.8.0
+[0.7.0]: https://github.com/yaminbkk/NexusMem/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/yaminbkk/NexusMem/compare/v0.5.4...v0.6.0
 [0.5.4]: https://github.com/yaminbkk/NexusMem/compare/v0.5.3...v0.5.4
 [0.5.3]: https://github.com/yaminbkk/NexusMem/compare/v0.5.2...v0.5.3

package/README.md

@@ -24,7 +24,7 @@ exists nowhere else, and it disappears when your terminal scrollback rolls over.
 **Contents:** [Try it](#try-it) · [Exact shell capture](#optional-exact-shell-capture) ·
 [Failure → fix chains](#failure--fix-chains-opt-in) · [How retrieval works](#how-retrieval-works) ·
 [Session summaries](#session-summaries-optional-local-model) · [Use it from an agent](#use-it-from-an-agent)
-· [What it costs you](#what-it-costs-you) · [Manual staleness & provenance](#manual-staleness--provenance) ·
+· [What it costs you](#what-it-costs-you) · [Staleness & provenance](#staleness--provenance) ·
 [Where it breaks](#where-it-breaks) · [Commands](#commands) · [Cross-project recall](#recall-across-projects)
 · [On disk](#on-disk) · [Development](#development)
 
@@ -48,11 +48,11 @@ Relevant history for: windows spawn failure
   readRepoInfo collapsed three unrelated failures into one error: git running and reporting
   the path is not a work tree, git not being installed, and the process failing to spawn at
   all. Dogfooding hit the third case in two separate sessions...
-- 2026-08-09 [inferred] README.md — Before a tagged release
+- 2026-08-09 [authored] README.md — Before a tagged release
   - [ ] Retry on transient process-spawn failures on Windows
 ```
 
-`[observed]`/`[inferred]` is the provenance tag (see [Manual staleness & provenance](#manual-staleness--provenance))
+`[observed]`/`[authored]` is the provenance tag (see [Staleness & provenance](#staleness--provenance))
 — a commit is a directly observed event, a doc section is a written claim that could go stale.
 
 A commit and a docs section, ranked against each other, inside whatever token budget you gave it.
@@ -269,19 +269,23 @@ Two things a memory layer needs and this one only partly has: a way to tell an o
 guess, and a way to retire a conclusion once something contradicts it. This section is what exists
 and what doesn't.
 
-Every node carries a `provenance`: `observed` (a commit that landed, a shell command's real exit
-code) or `inferred` (a conversation turn, a session summary, a doc section — all readable as claims
-that could be wrong or go stale). Set once per collector at ingest time, shown as a `[observed]` /
-`[inferred]` tag on every query result, and now used to decay retrieval weight too — `inferred` nodes
-fade from ranking twice as fast as `observed` ones as they age.
+Every node carries a `provenance`, a four-tier trust hierarchy set once per collector at ingest
+time: `observed` (a commit that landed, a shell command's real exit code) > `authored` (a doc
+section — a human's own written claim) > `recorded` (a conversation turn — verbatim, but talk about
+events rather than the events) > `derived` (a session summary — a model's distillation). The tier is
+shown as a tag on every query result and decays retrieval weight — the lower the trust, the faster a
+node fades from ranking as it ages. The ordering is the design claim; the exact decay ratios are
+judgment calls, not measured optima.
 
 ```bash
 nexusmem stale
 ```
 
-Lists `inferred` nodes old enough (45+ days by default) that nothing has confirmed they still hold —
-a heuristic on age and provenance, not on content. It writes nothing; you decide which candidates are
-actually wrong.
+Lists non-`observed` nodes old enough (45+ days by default) that nothing has confirmed they still
+hold — a heuristic on age and provenance, not on content. It writes nothing; you decide which
+candidates are actually wrong. Any candidate the SLM has already flagged (see below) is decorated
+with its standing `likely superseded by` suggestion — reading those costs nothing, so the plain
+command stays instant and offline.
 
 ```bash
 nexusmem mark-stale <oldNodeId> --supersedes <newNodeId>
@@ -290,10 +294,27 @@ nexusmem mark-stale <oldNodeId> --supersedes <newNodeId>
 Links `newNodeId` as the replacement for `oldNodeId`. The ranker down-weights the old node from then
 on (it stays queryable, just usually loses to its replacement) — nothing is deleted, unlike `forget`.
 
-**What this doesn't do:** nothing here reads content to detect a real contradiction. If a later commit
-contradicts an earlier doc section, `nexusmem stale` won't know that specifically — it only knows the
-doc section is old and inferred. Actual contradiction detection (comparing what two nodes claim, not
-just how old one is) is still an open problem.
+```bash
+nexusmem stale --check-contradictions
+```
+
+For each candidate, finds the most similar newer node (local embedding search) and asks a local SLM
+(Ollama, `qwen2.5:3b` by default) whether it actually contradicts the older one — real content
+comparison, not just age. A match is printed as `likely superseded by <id> <title> -- <reason>`
+under the candidate. Every judgment (either verdict) is memoized, so a judged pair is never sent to
+the model again; nothing else is written — `supersedes` stays yours to set via `mark-stale`.
+
+**This also runs automatically during `sync`** — at most 3 new judgments per run (configurable via
+the `contradictions` block in `.nexusmem/config.json`; set `autoCheck: false` to turn it off), only
+when the embedding provider was reachable anyway, and free on repeat syncs thanks to the
+memoization. New and open suggestions show up in the sync summary, `nexusmem status` (a `flagged`
+line), and plain `nexusmem stale`.
+
+**What this doesn't do:** it is one small model's yes/no judgment on one older/newer pair, not a
+verified fact — treat a match as a lead to check, not a conclusion. It also only ever compares a
+candidate against nodes *found by embedding similarity*; a contradiction from an unrelated-sounding
+node would never surface. Comprehensive contradiction detection (not just for the pair the vector
+search happens to surface) is still an open problem, and nothing here supersedes a node on its own.
 
 ## Where it breaks
 
@@ -361,8 +382,9 @@ just how old one is) is still an open problem.
 ## Commands
 
 `init`, `sync`, `query <text>`, `status` (add `--share` for a plain-text summary worth pasting
-somewhere), `projects`, `mcp`, `forget <value>`, `stale`,
-`mark-stale <nodeId> --supersedes <newNodeId>`, and `hook install|remove|status`.
+somewhere), `projects`, `mcp`, `forget <value>`, `stale` (add `--check-contradictions` for a local-SLM
+content check, see above), `mark-stale <nodeId> --supersedes <newNodeId>`, and
+`hook install|remove|status`.
 
 There are also five dry-run previews (`scan-git`, `scan-diff`, `scan-shell`, `scan-docs`,
 `scan-conversation`)