Skip to content

Releases

mnemo 6.2.1

Choose a tag to compare

@github-actions github-actions released this 17 Jul 03:08
2462db9

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=false to stay fast, so
      ingest.reindex_events ran with embedder=None and stored the node
      unembedded. A later reindex with an embedder then saw an unchanged file hash
      and took the unchanged branch -- so the embed was never retried. Forever.
    • The git-log walk upserted commit nodes without embedding them at all.
    • embed.embed_all_unembedded already implemented the exact repair, but nothing
      in production ever called it (only scripts/smoke_ingest.py did).
  • 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=false stays a strict no-embed fast path, so
    the hook keeps its speed.
  • Visibility. The repair is never silent: ReindexReport.embedded_backfilled,
    the done event, and POST /v1/reindex all report the count (steady state 0).
  • mnemo doctor gains an embedding coverage check 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

Choose a tag to compare

@github-actions github-actions released this 16 Jul 09:37
2afd9cf

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_lead 0.690 0.079 0.400
    weighted_rrf (new default) 0.881 0.184 0.550

    rrf_k=60 is the literature default, not a value fitted here (a 10..200 sweep is
    smooth and unimodal around it), and every w_bm25 in 0.5..1.0 beat the old
    default. Tunable via rrf_k / rrf_weight_bm25 / rrf_weight_vector.

  • Eval set expanded 42 -> 80 and tagged by query_type (lexical|conceptual);
    mnemo eval now 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 caught bm25_lead regressing 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@1 is 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

Choose a tag to compare

@github-actions github-actions released this 18 Jun 13:24
6801014

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.

  • rule node type -- author one .md per rule with a rule: 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 by governance.py; malformed rules fail open (advisory,
    never crash). New /mnemo-rule-add skill.
  • 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
    block rules. Default mode warn (surface, never block); set
    MNEMO_GOVERNANCE_MODE=block to enforce, MNEMO_GOVERNANCE_BYPASS=1 to
    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

Choose a tag to compare

@github-actions github-actions released this 11 Jun 10:14
69b0173

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-calls blast radius), provenance (code -> commit
    -> memory walk), and memory_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@k is deliberately absent from the headline (the existing
    mnemo eval keeps it as a secondary diagnostic).
  • eval_tasks module -- a dependency-free core (Task/TaskResult,
    score_task, run_tasks(solve_fn), aggregate_tasks,
    format_task_report) mirroring eval_retrieval's caller-owns-execution
    seam, plus a deterministic ORACLE solver (the canonical tool path per
    class) and a graph-driven task generator. The solve_fn seam 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
    returned file::name refs 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

Choose a tag to compare

@github-actions github-actions released this 11 Jun 07:56
f0a544d

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, the full_source endpoint,
    the UI language hint) reads the range via a shared code_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; --apply for the live store) reports
    rekeyed / would-orphan / id-preserved before the migration is trusted.
  • Reindex mtime-skip. A new file_index table records each code
    file's mtime; an unchanged code_repo file 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 eval expanded 14 -> 42 queries + a pinned corpus snapshot
    (node count + fingerprint) in the report header so two runs are
    comparable.

mnemo 5.27.0

Choose a tag to compare

@github-actions github-actions released this 11 Jun 03:41
18fc5d2

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_fts virtual 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_search gives 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

Choose a tag to compare

@github-actions github-actions released this 10 Jun 07:41
14ffc8e

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
    keyed mnemo-daemon while its path derives D--Repository-knowledge-base;
    the union tripled hit@5 with zero ranking changes.) retrieve.query
    gains active_projects; the UserPromptSubmit hook forwards cwd to
    /v1/query (new optional QueryIn.cwd); the server resolver slots the
    request-level cwd between the explicit key and the daemon-global
    workspace; mnemo query auto-scopes by default (--no-auto-scope /
    --project to override); MCP queries auto-scope from the server process
    cwd and every mnemo_query response carries a scope field
    ({project_keys, auto}).
  • "Not indexed -- want to index it?" (user spec). When the session
    starts in a .git directory whose project has zero indexed nodes, the
    visible banner appends the mnemo source add <cwd> offer and the model
    context tells Claude it may offer the indexing commands -- asking first;
    never auto-index. The first MCP mnemo_query notice 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

Choose a tag to compare

@github-actions github-actions released this 10 Jun 06:49
aa0a263

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-line systemMessage the 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 statusline prints a one-line presence cue for
    Claude Code's status bar (mnemo <count> / mnemo offline, plus up{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.json non-clobbering (only when no statusLine exists; skip with
    --no-statusline / -NoStatusline), and mnemo doctor gains an advisory
    statusline check.
  • mnemo_help + grep-nudges (MCP-only hosts). New mnemo_help (safe,
    no-arg) tells a model what mnemo is + to prefer mnemo_query over grep for
    how/where/why questions; the mnemo_query / mnemo_search_by_type
    descriptions lead with that nudge, and the first mnemo_query result 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.cli is on a diet (heavy modules function-local; hook spawn
    0.74s -> 0.38s, locked by a test); the Embedder tries local_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

Choose a tag to compare

@github-actions github-actions released this 09 Jun 09:43
48d74ef

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/mnemo then
    /plugin install mnemo@mnemo registers the plugin the supported way --
    surfacing the 11 /mnemo-* commands + the hooks + skills.
  • Fixed plugin.json. Dropped the invalid bare-string commands/skills
    path keys (both auto-discovered) and the fictional platforms hook key;
    hooks now reference the canonical ./hooks/hooks.json.
  • Cross-platform hooks via mnemo hook <event>. The 6 .sh/.ps1 hook
    scripts are replaced by one CLI group (mnemo hook session-start /
    user-prompt-submit / post-tool-use) wired from hooks/hooks.json in the
    real nested CC schema. No platforms selector, no python3-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-setup skill walks an agent through the
    whole chain (engine -> MCP registration -> the /plugin commands -> doctor).
  • Rewritten installers. install.sh / install.ps1 drop the obsolete
    symlink step; they register the mnemo mcp server (claude mcp add), print
    the two /plugin commands, and point at mnemo 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

Choose a tag to compare

@github-actions github-actions released this 09 Jun 06:39
758d1e7

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 + a node_hash
    body fingerprint. POST .../apply requires that node_hash back and
    re-verifies the live body still matches (409 if it drifted), then edits
    the body + marks the finding resolved. 404 unknown / 422 not-applyable.
  • New MCP tool mnemo_apply_finding (risk=confirm; 28 -> 29): call
    without confirm_node_hash to preview, with it to apply. The host's
    confirm-prompt is the second gate.
  • UI. /analyze orphan 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.