README
¶
nova-memory
What it is
nova-memory: search your own markdown notes, and check a draft against what they already say
Why use it
Find a note without rereading everything.
Install
go install github.com/mas-bandwidth/nova-tools/cmd/nova-memory@latest
nova-memory version
First run
The transcript below is executed line for line by the docs tests; the full record is in docs/TESTS.md.
Fixture: cmd/nova-memory/testdata/corpus.
$ nova-memory quickstart --root ./corpus
QUICKSTART RUN root=./corpus steps=3 channels=bm25 k=3/2 words-source=corpus-top-terms candidate=corpus-first-paragraph words="glazing minutes pressure"
$ nova-memory stats --root ./corpus
STATS OK schema=nova-memory/2 files=6 chunks=20 bytes=4866 vocab=380 avg-terms=39.3 build=822.917µs
STATS OK class=. chunks=3
STATS OK class=log chunks=4
STATS OK class=notes chunks=13
$ nova-memory search --root ./corpus --channels bm25 --k 3 glazing minutes pressure
SEARCH OK hits=3 k=3 channels=bm25 files=6 chunks=20: query="glazing minutes pressure"
SEARCH CAL score=4.05 score-channel=bm25 probe=unrelated-control
SEARCH HIT rank=1 score=3.48 score-channel=bm25 fused=0.01667 class=notes name=lantern-care type=measured root=./corpus: notes/lantern.md:13 "Measured over one winter: glazing washed weekly held its polish; glazing\nwashed monthly needed grinding twice. The weekl…"
SEARCH HIT rank=2 score=3.12 score-channel=bm25 fused=0.01639 class=notes name=- type=- root=./corpus: notes/index-notes.md:8 "- [lantern-care](lantern.md) — the glazing, the brass, and the two cloths\n- [tide-tables](tides.md) — the jetty's ei…"
SEARCH HIT rank=3 score=2.97 score-channel=bm25 fused=0.01613 class=notes name=fog-signal type=measured root=./corpus: notes/fog-signal.md:8 "The diaphone runs on compressed air, and the compressor needs eleven minutes\nto bring the receiver to working pressure f…"
SEARCH NOTE lexical only — a paraphrase sharing almost no vocabulary with the corpus will not surface in any lexical top-k, and no channel here is semantic
QUICKSTART DEMO no --draft given, so the candidate on stdin is this corpus's own first paragraph: HANDBOOK.md:3
$ nova-memory check --root ./corpus --channels bm25 --k 2 -
MEMORY OK candidates=1 source=- k=2 channels=bm25 files=6 chunks=20
MEMORY CAL score=4.05 score-channel=bm25 probe=unrelated-control
MEMORY CAND n=1: "This fixture corpus belongs to an invented lighthouse station. It exists so\nthat nova-memory's verbs…"
MEMORY HIT cand=1 rank=1 score=90.20 score-channel=bm25 fused=0.01667 class=. name=- type=- root=./corpus: HANDBOOK.md:3 "This fixture corpus belongs to an invented lighthouse station. It exists so\nthat nova-memory's verbs can be exercised …"
MEMORY HIT cand=1 rank=2 score=15.01 score-channel=bm25 fused=0.01639 class=log name=- type=- root=./corpus: log/1974-03-11.md:11 "Left a note to write up the [[storm-glass]] readings against the barometer\none day, because the two disagree in a way th…"
MEMORY NOTE lexical only — a paraphrase sharing almost no vocabulary with the corpus will not surface in any lexical top-k, and no channel here is semantic
MEMORY NOTE this verb asserts nothing and never exits 1: it hands you k receipts and the verdict stays yours
MEMORY NOTE a hit in a dated log class is evidence the event was recorded, not that the lesson was banked — the class on each receipt is the distinction
QUICKSTART OK done=3
QUICKSTART NOTE this used bm25 alone and k=3/2; those are choices, not defaults: see --channels and --k
Verbs
The nova-memory section of the command reference documents every verb's flags, effect and exit codes.
versionquickstartstatssearchcheckverifyevalboot
Spec
The contract is docs/SPEC.md.
Documentation
¶
Overview ¶
nova-memory makes membership in a markdown corpus a LOOKUP, never a scan.
WHAT IT IS FOR. A mind that keeps its memory as markdown answers "do I already know this?" by re-reading everything it is, and that cost grows with every day lived: consolidating n new learnings against m existing ones is O(n*m), and m only ever gets bigger. This tool rebuilds an in-memory index from the corpus on every run and answers membership questions with top-k receipted candidates, so the mind's judgment budget per new learning is k — a constant — however large the corpus grows.
WHAT IT REFUSES TO BE. Not a write path (it never touches the corpus), not a judge (the author decides after the receipts), not the boot (query for WORK, traverse for SELF — a relevance-ranked lens must not replace the linear read that meets what you did not ask for), and not authoritative (the tree is the store; the index stops existing when the process exits).
Every path, every scope, and every budget comes from a flag. There are no defaults, no config file, and no environment variable: a missing flag is a refusal, never a guess. Exit 0 ran and passed, 1 ran and failed, 2 could not run.
nova-memory version: which build is running.
A refusal, a green or a line somebody pastes into a note is evidence about a BUILD, and until this verb existed this binary could not say which one it was: `nova-memory version` was exit 2, unknown subcommand. So "we are all running the same nova-memory" was a belief rather than a reading, and the release could not assert over the set what no member of the set would answer.
The version is NOT a constant maintained by hand -- a hand-maintained constant is wrong exactly at the commit after the release, where it still names the release. It is read from the build itself by pkg/buildinfo, which holds the resolution order and the shape of the line for every binary here, so that eleven tools answer this question in one spelling rather than eleven.
Source Files