Repository navigation
Releases
mnemo 6.2.1
Fix: 22% of the index was invisible to semantic search. Reindex now guarantees every node is embedded.
Found by dogfooding v6.2.0: the freshly written session handover would not surface
in mnemo's own graph. 4,106 of 18,661 live nodes (22.0%) had zero embeddings --
including 100% of commit nodes, 100% of code_endpoint nodes, and the two
most recent session handovers, meaning the canonical entry-point memory could not
be recalled by meaning at all. BM25/FTS5 still indexed every one of them, so
nothing ever errored and no count looked wrong. A textbook silent zero.
- Root cause. Two independent paths created nodes that never got embedded, and
one skip rule made it permanent:- The PostToolUse hook nudges
POST /v1/reindex?embed=falseto stay fast, so
ingest.reindex_eventsran withembedder=Noneand stored the node
unembedded. A later reindex with an embedder then saw an unchanged file hash
and took theunchangedbranch -- so the embed was never retried. Forever. - The git-log walk upserted
commitnodes without embedding them at all. embed.embed_all_unembeddedalready implemented the exact repair, but nothing
in production ever called it (onlyscripts/smoke_ingest.pydid).
- The PostToolUse hook nudges
- Fix. A reindex that has an embedder now enforces one creation-path-agnostic
invariant at the end of the run: no node is left unembedded. Fixing each
creation site would have been whack-a-mole -- there are at least three, and the
next one added would have regressed it silently. Free in steady state (one query
that finds nothing to do);embed=falsestays a strict no-embed fast path, so
the hook keeps its speed. - Visibility. The repair is never silent:
ReindexReport.embedded_backfilled,
thedoneevent, andPOST /v1/reindexall report the count (steady state 0). mnemo doctorgains anembedding coveragecheck reporting unembedded nodes
and the percentage, so this class of failure can never hide again.
Note for anyone who has been running mnemo for a while: your first mnemo reindex
on 6.2.1 may take noticeably longer than usual while it backfills. That is the
repair; subsequent runs return to normal.
mnemo 6.2.0
Retrieval fusion rebalance -- rank-level weighted RRF is the new default ranking. Measured +0.23 hit@5 overall, and it wins on BOTH halves of the query distribution.
Retrieval was the weak link the v6.0.0 reliability baseline exposed. The 6-term
weighted sum blended the dense-vector and BM25 rankers at the SCORE level, which
under-weighted the far stronger lexical signal. The fix is rank-level fusion.
-
config.fusion_mode-- the vector<->lexical relevance core is now a swappable
seam:weighted_rrf(new default),weighted_sum(the previous behaviour, kept
as the escape hatch and the comparable baseline),bm25_lead. The CONTEXT terms
(graph / recency / type / project) and the multiplicative finishers (exact-name
boost, isolation penalty) are orthogonal and unchanged in every mode, so a
mode A/B measures one change rather than two. Every mode scores into the same
[0, alpha+zeta]band. An unknown mode fails open to the default. -
Measured on an 80-query set (42 lexical + 38 conceptual) against one pinned
corpus of 18,656 nodes, hit@5:mode lexical conceptual overall weighted_sum(old default)0.500 0.132 0.325 bm25_lead0.690 0.079 0.400 weighted_rrf(new default)0.881 0.184 0.550 rrf_k=60is the literature default, not a value fitted here (a 10..200 sweep is
smooth and unimodal around it), and everyw_bm25in 0.5..1.0 beat the old
default. Tunable viarrf_k/rrf_weight_bm25/rrf_weight_vector. -
Eval set expanded 42 -> 80 and tagged by
query_type(lexical|conceptual);
mnemo evalnow breaks hit@1/hit@5/MRR down per type. This is what makes the
lexical-vs-semantic tradeoff of a ranking change visible instead of hidden inside
one blended average -- and it is what caughtbm25_leadregressing conceptual
recall. The 38 conceptual queries were authored from corpus ground truth and
adversarially verified (a candidate was rejected if a keyword search on the
prompt's own words found the answering file -- that would make it lexical). -
Known limitation:
hit@1is roughly flat (0.175 -> 0.188). RRF reliably gets
the right node INTO the top-5 without sharply ordering the top; mnemo injects
k=5 cited nodes, so hit@5 is the operative metric. -
Known weak spot (next lever, now evidence-backed): conceptual retrieval is
poor in absolute terms (0.184). Prose questions surface CODE nodes because the
corpus is ~17.4k code vs ~1.2k prose nodes and the type-priority weight cannot
overcome those odds. Fusion cannot fix this; prose-vs-code ranking and a harder
project-isolation penalty can.
mnemo 6.1.0
Governance layer -- mnemo now tells an agent what to do and NOT do, and enforces it with teeth.
Beyond passive knowledge injection: coding constraints, workflow gates, specs,
mandatory verification, and code review become first-class rule nodes that
mnemo surfaces prescriptively at the right moment and (opt-in) enforces by
blocking a tool call or session end until a mandatory step is provably
satisfied.
rulenode type -- author one.mdper rule with arule:frontmatter
block:modality(MUST/MUST_NOT/SHOULD),enforcement
(inform/warn/require-ack/block),applies_to(glob/intent/tool +
tool_arg_match),verify(command + expected exit),requires_step.
Parsed read-side bygovernance.py; malformed rules fail open (advisory,
never crash). New/mnemo-rule-addskill.- Prescriptive injection -- binding MUST/MUST_NOT rules surface in a new
## Active rules (mnemo)block above the ranked memory, via a separate
deterministic fetch that bypasses the injection token budget. - Evidence ledger -- a mandatory step is satisfied only by CAPTURED proof
(a verify command's real exit code, via the PostToolUse hook), and the
evidence must be fresher than the latest edit -- an edit after a verify
re-opens the gate. The agent cannot self-assert compliance. - Hard enforcement -- PreToolUse denies/asks and Stop blocks against
blockrules. Default modewarn(surface, never block); set
MNEMO_GOVERNANCE_MODE=blockto enforce,MNEMO_GOVERNANCE_BYPASS=1to
override. Every gate is fail-open -- a daemon/store error never blocks a
tool call or a session.
Additive: no MCP surface change (rule-query tools deferred); built on the
v5.28 stable keys + v6.0 reframe. The analyzer "governance lens" (code-review
engine) and the /rules UI are follow-on releases (v6.2/v6.3).
mnemo 6.0.0
Agentic task-success harness -- opens the reliability arc by measuring the moat, not snippet hit@k.
Single-shot hit@k is the wrong reliability bar: it measures snippet
retrieval -- the commodity axis where a coding agent's own grep+read loop
already wins -- and never measured the two things grep cannot do, which are
mnemo's actual moat: the typed graph (blast radius, provenance) and
cross-session memory. v6.0.0 ships the instrument to measure THAT first
(measure-before-tuning); the injection-as-pointer and navigable-refs changes
follow once the baseline is in hand.
mnemo eval-tasks-- a new task-success eval over three moat classes:
structural(reverse-callsblast radius),provenance(code -> commit
-> memory walk), andmemory_recall(retrieval over memory nodes). Scores
whether mnemo's tools can answer a question in <= the task's call budget;
the report LEADS with per-class moat success and a pinned corpus snapshot.
hit@kis deliberately absent from the headline (the existing
mnemo evalkeeps it as a secondary diagnostic).eval_tasksmodule -- a dependency-free core (Task/TaskResult,
score_task,run_tasks(solve_fn),aggregate_tasks,
format_task_report) mirroringeval_retrieval's caller-owns-execution
seam, plus a deterministic ORACLE solver (the canonical tool path per
class) and a graph-driven task generator. Thesolve_fnseam leaves a
clean drop-in for a future LLM-agent solver.- Hybrid task fixture (
tasks_eval.json, 26 tasks) -- generated from the
graph, then hand-curated + independently verified. - First baseline (17,964-node corpus): structural 1.00 / provenance 1.00
recall / memory_recall 0.75; overall 0.92 success at avg 1.0 calls. The
graph moat is the reliable part; retrieval is the weak link -- empirically
confirming the reframe. (Built on v5.28's stable keys, which make the
returnedfile::namerefs durable across reindexes.)
This is the measurement foundation, not the full reliability payoff: the
injection-as-pointer and navigable-refs cuts are the next releases.
mnemo 5.28.0
Stable code-node identity + reindex mtime-skip (workstream C, part 3 -- closes the make-it-real arc; lesson #129).
Code declaration nodes keyed by <file>:<start>-<end> re-keyed on every
line shift, churning hundreds of nodes per reindex (delete + recreate +
re-embed, losing each node's id and its edges / feedback / history).
v5.28.0 moves them to a line-stable <file>::<qualified_name> key with the
line range demoted to frontmatter metadata.
- Stable identity key. The parser assigns
<file>::<qualified_name>
(methods -><Class>.<method>; same-name collisions get a document-order
ordinal) in one post-build pass; the line range moves to
frontmatter.code_unit. Every stored-node consumer of the old suffix
(the Tier-2 calls resolver, git-log overlap, thefull_sourceendpoint,
the UI language hint) reads the range via a sharedcode_file_and_range
helper, with a legacy-suffix fallback. - Lazy in-place migration. On reindex, a stable-key miss on a code
declaration matches the legacy line-range node by(file, type, name)
and re-keys it IN PLACE (rekey_node) -- preserving the node id (hence
edges, feedback, audit refs) and the embedding -- instead of churning.
Dry-run on the live 17,958-node corpus: 12,978 of 12,983 legacy code
nodes re-keyed in place, 0 left legacy, 5 real orphans, 100% id
preserved. - Dry-run gate.
mnemo migrate-code-identity(default: dry-run on a
throwaway DB copy;--applyfor the live store) reports
rekeyed / would-orphan / id-preserved before the migration is trusted. - Reindex mtime-skip. A new
file_indextable records each code
file's mtime; an unchangedcode_repofile is skipped (not re-parsed) on
reindex -- gated so a file with any remaining legacy-keyed node is never
skipped (the migration always runs first). mnemo evalexpanded 14 -> 42 queries + a pinned corpus snapshot
(node count + fingerprint) in the report header so two runs are
comparable.
mnemo 5.27.0
Exactness: lexical recall + exact-name + NULL-key fix (workstream C, part 2).
Beat the v5.26.0 baseline. Measured on the live 18,073-node corpus via
mnemo eval: hit@1 0.14 -> 0.21, hit@5 0.21 -> 0.36 (+71%), MRR
0.16 -> 0.25.
- FTS5/BM25 lexical channel. New
nodes_ftsvirtual table (name +
description + 32 KB body cap), kept in lockstep on upsert/delete, with a
self-healing rebuild when its row count drifts from the node count.
bm25_searchgives retrieval lexical RECALL -- a name-exact node that
misses the vector top-40 (long prose dominates embeddings) now becomes a
candidate. - RRF-style fusion + exact-name finisher. The BM25 rank fuses into the
existing zeta/lexical component (max(substring_fraction, 1/(1+rank));
no new weight, the auto-tuner contract is untouched), and a candidate
whose name appears verbatim in the prompt (>= 4 chars) gets a final-score
boost (cfg.exact_name_boost, default 1.25) -- the same multiplicative
pattern as the project-isolation penalty. - NULL-key derivation + backfill. Directory sources (code_repo /
docs_dir / plan_dir / memory_dir) registered without a project_key made
every owned node cross-cutting (the v1.2.1 contract), leaking foreign
docs into every scoped query. Reindex now derives the key from the
source root, persists it, and backfills owned NULL-key nodes
(claude_md stays None -- global memory is cross-cutting by design).
Live: NULL-keyed nodes dropped 2289 -> 353.
Remaining eval misses (deferred to v5.28.0): snake_case-vs-spaced
tokenization, a code-node boost for how/where questions, and indexing the
repo-root install scripts. No new deps; FTS5 ships in CPython's sqlite.
mnemo 5.26.0
Precision baseline + auto-scoped retrieval (workstream C, part 1).
"No tuning without a baseline" + the cross-project leak fix. Strict
isolation has existed since v1.2 -- the leak was that no production caller
passed an active project. Now every entry point auto-detects it.
mnemo eval+ the precision harness. A labelled 14-query SELF set
(real "where/how is X in mnemo" questions with known answering files), a
pure hit@k/MRR scorer, and a CLI report instrument. Official baseline on
the live 17,940-node corpus: hit@1=0.14, hit@5=0.21, MRR=0.16 -- the
numbers v5.27.0's exactness work (BM25/RRF/chunking) must beat.- Multi-key cwd auto-scoping.
retrieve.resolve_auto_scope(store, cwd)
derives the active project key SET from the caller's working directory:
the path-derived key plus every source-declared key rooted at/under/above
cwd, each applied only when it owns nodes. (Measure-first caught
single-key scoping BLINDING a repo to its own code -- mnemo's code is
keyedmnemo-daemonwhile its path derivesD--Repository-knowledge-base;
the union tripled hit@5 with zero ranking changes.)retrieve.query
gainsactive_projects; the UserPromptSubmit hook forwardscwdto
/v1/query(new optionalQueryIn.cwd); the server resolver slots the
request-level cwd between the explicit key and the daemon-global
workspace;mnemo queryauto-scopes by default (--no-auto-scope/
--projectto override); MCP queries auto-scope from the server process
cwd and everymnemo_queryresponse carries ascopefield
({project_keys, auto}). - "Not indexed -- want to index it?" (user spec). When the session
starts in a.gitdirectory whose project has zero indexed nodes, the
visible banner appends themnemo source add <cwd>offer and the model
context tells Claude it may offer the indexing commands -- asking first;
never auto-index. The first MCPmnemo_querynotice says the same.
No scoring-weight changes (that is v5.27.0, measured against this
baseline); deterministic retrieval for unscoped calls is byte-stable.
mnemo 5.25.0
Discover & presence -- make mnemo visibly there, in Claude Code and beyond.
v5.24.0 made mnemo a registered Claude Code plugin (commands appear, hooks
fire), but the other half of the complaint stood: "no notify, nothing related
to mnemo -- it lives alongside other tools invisibly." This release makes
mnemo present to the human in Claude Code and discoverable to the model in
the six MCP-only hosts.
- User-visible session-start banner. The SessionStart hook now emits a
JSON object: a one-linesystemMessagethe HUMAN sees ("mnemo: N memories
across M source(s) -- /mnemo-query to recall") alongside the model-only
memory map (additionalContext, unchanged). Opt out with
MNEMO_NO_SESSION_BANNER=1. - Status line. New
mnemo statuslineprints a one-line presence cue for
Claude Code's status bar (mnemo <count>/mnemo offline, plusup{N}
from a per-session inject count). A short health probe that never opens the
store and returns as soon as the daemon answers, so it never blocks the bar. The installers wire it into
settings.jsonnon-clobbering (only when no statusLine exists; skip with
--no-statusline/-NoStatusline), andmnemo doctorgains an advisory
statusline check. mnemo_help+ grep-nudges (MCP-only hosts). Newmnemo_help(safe,
no-arg) tells a model what mnemo is + to prefermnemo_queryover grep for
how/where/why questions; themnemo_query/mnemo_search_by_type
descriptions lead with that nudge, and the firstmnemo_queryresult per
process carries a one-time discovery notice. MCP surface 29 -> 30.- Docs. Integration mount guides + the integrations README + wire-schema
now say 30 tools (12 safe / 14 confirm / 4 danger); README's install section
describes the v5.24.0 marketplace model instead of the obsolete symlink. - Cheap hooks (live-profiling driven). Presence must not cost a CPU: live
diagnosis showed every prompt spawning a python that loaded the embedder
WITH a HuggingFace Hub round-trip (~50s when rate-limited), every memory
edit spawning an unguarded full-corpus reindex subprocess (4 concurrent
observed), and every spawn paying ~0.7s of module-top imports. Now the
per-prompt hook asks the RUNNING daemon (POST /v1/query, warm model) and
falls back in-process only when it is down; the post-tool-use hook nudges
POST /v1/reindex?embed=false(server-side single-flight; 409 = already
running) instead of spawning, with the subprocess fallback debounced (60s);
import mnemo.cliis on a diet (heavy modules function-local; hook spawn
0.74s -> 0.38s, locked by a test); the Embedder trieslocal_files_only
first (zero Hub contact once cached); and hook stdin parsing tolerates the
UTF-8 BOM Windows shells prepend (as U+FEFF or cp1252 mojibake) instead of
silently failing open.
No new runtime dependencies. Per-prompt auto-injection stays token-budgeted
(<=800); presence is one banner line (opt-out) + one statusline line, never
per-prompt spam.
mnemo 5.24.0
Install & register -- make mnemo a real, discoverable Claude Code plugin.
mnemo shipped 20+ green releases yet stayed invisible: no slash commands, no
hook output, "nothing related to mnemo." Root cause: mnemo was never a
registered Claude Code plugin -- it shipped no marketplace manifest, its
plugin.json used a fictional platforms hook key + a flat shape Claude Code
does not understand (so the hooks would never fire even if loaded), and the
installer only symlinked the repo into ~/.claude/plugins/ -- which modern,
marketplace-driven Claude Code ignores. This release makes mnemo actually
install + register, verified against the live Claude Code plugin contract.
marketplace.json. New.claude-plugin/marketplace.json(single-repo,
source: "./") so/plugin marketplace add mmct-jsc/mnemothen
/plugin install mnemo@mnemoregisters the plugin the supported way --
surfacing the 11/mnemo-*commands + the hooks + skills.- Fixed
plugin.json. Dropped the invalid bare-stringcommands/skills
path keys (both auto-discovered) and the fictionalplatformshook key;
hooks now reference the canonical./hooks/hooks.json. - Cross-platform hooks via
mnemo hook <event>. The 6.sh/.ps1hook
scripts are replaced by one CLI group (mnemo hook session-start/
user-prompt-submit/post-tool-use) wired fromhooks/hooks.jsonin the
real nested CC schema. Noplatformsselector, nopython3-on-PATH
dependency, and the logic is now unit-tested Python. Each hook fails open. mnemo doctor. A loud end-to-end verifier: PATH, index, plugin
registration (the link that was silently broken), daemon, MCP -- an
[ok]/[FAIL]/[?]checklist with a concrete fix per problem; exits
nonzero if a required link is broken. Replaces the old silent fail-open.- AI-executable install. New
mnemo-setupskill walks an agent through the
whole chain (engine -> MCP registration -> the/plugincommands -> doctor). - Rewritten installers.
install.sh/install.ps1drop the obsolete
symlink step; they register themnemo mcpserver (claude mcp add), print
the two/plugincommands, and point atmnemo doctor.
MCP stays registered separately (not bundled in the plugin): bundling would
rename the tools mcp__plugin_mnemo_* and mnemo's Python venv cannot live in
the git-copied plugin cache. The 29-tool MCP surface is unchanged.
mnemo 5.23.0
Phase 4b: confirm-then-apply -- the first node mutation.
The auditor can now FIX a finding, not just surface it. v5.23.0 adds a
deterministic, hard-gated apply for orphan_reference findings: it removes
the dead [mnemo:<id>] citation token(s) from the node body. No LLM. Every
apply is previewed + confirmed; nothing is bulk-applied.
- Deterministic orphan-fix. Strips only the dead, id-shaped (32-hex)
citation targets, leaving valid citations + all other text. Documentation
placeholders ([mnemo:<id>],[mnemo:node_id]) are refused -- a
finding is applyable only when it cites a real, currently-missing node id. - Preview -> confirm handshake.
POST /v1/analyze/queue/{fp}/apply/preview
(read-only) returns the before/after + the removed tokens + anode_hash
body fingerprint.POST .../applyrequires thatnode_hashback and
re-verifies the live body still matches (409 if it drifted), then edits
the body + marks the findingresolved. 404 unknown / 422 not-applyable. - New MCP tool
mnemo_apply_finding(risk=confirm; 28 -> 29): call
withoutconfirm_node_hashto preview, with it to apply. The host's
confirm-prompt is the second gate. - UI.
/analyzeorphan rows get an Apply button -> a modal shows the
before/after diff + the exact removed tokens -> Confirm applies. One
finding at a time, no bulk apply.
Anti-goals held: no silent edits (preview + node-hash confirm + a risk=confirm
tool); no LLM; orphan_reference + id-shaped targets only. Additive: +1 module
(apply.py), +2 endpoints, +1 tool, +UI; the 28 prior tools + the read-only
queue stay byte-stable.