memai-maintenance

memai-maintenance — the MemAI curation pass

Entry point of the maintenance pass. It does not do the fine-grained work — it coordinates the four specialized skills, owns what none of them covers (domain tree, diagrams, decay), and folds every result into a single optimize_stage run.

Proposer → disposer. This pass applies nothing on its own: it collects the sub-skills' suggestions and hands them to the dashboard through optimize_stage. The human applies or rejects each one there (a backup is taken before the first apply; every apply can be undone). Apply directly (set_confidence/edit_memory/link_memories/forget/also_domain) only when the user asks for it without the dashboard.

help() is the source of truth for the tools — signatures read live from the code. When unsure of a name or an argument, call help before trusting this file.

Dashboard: http://127.0.0.1:8888 (default port). The MCP server can bring it up alongside itself when MEMAI_ADMIN_AUTOSTART is set; otherwise run-admin.bat.

0. Pre-flight (done ONCE; the sub-skills reuse it)

The orchestrator warms up once and keeps the result in context for every sub-skill. Read each source once; nothing below is read twice.

1. pulse(domain) — the state a scope inherits, plus:
   • scope — what the scope HOLDS next to what came back: subdomains (own = filed exactly there, subtree = with descendants) and not_shown per list (a warm-up stops at a handful; this counts what it left behind). Read it as the drill-down plan: list_by_domain(domain, type=…) / search(query, domain=…) on the child that was only counted.
   • scope.paths — which path(s) the name given actually resolved to (§2).
   • scope.stale — how many memories in the scope carry a review_after date that has passed. Present only when non-zero, and the pass's own work list (§4, step 3).
   • diagrams — the documented flows by title only, never inlined. Open one with get_diagram(uid, format='json').
2. list_domains() — the tree, not a list: per entry parent, depth, count (filed at exactly that path), subtree (that plus its descendants), children, implicit (a level that exists only because something deeper is filed below it), plus also/subtree_also for what is cross-listed there and not filed. count: 0 with also > 0 is a pure cross-cutting subject.
3. get_domain_case() — the store's casing policy: preserve | lower | upper, preserve by default. It governs writes; reads fold case either way (§2).
4. optimize_runs() — take the created_at of the latest run. The scan is incremental: optimize_scan(since="<that created_at>") reviews only the delta (a full scan on the first pass, or on request). The fields that drive the pass:
   • stats — over the whole filtered corpus, independent of limit, including due_for_review, never_recalled, untagged and untitled;
   • untagged — memories whose tags are empty, or are nothing but the type every read already filters on. Retrieval is BM25 over content, tags and domain, so those rows answer only queries that quote their own wording. They are the work list for retag: give each the identifier, the symbol and the plain-language phrasing someone will type;
   • untitled — memories with no title, listed everywhere by the opening line of their body. They are the work list for retitle: name each one by its subject, in the words someone would look for it by. The title outweighs every other field in BM25, so this is retrieval work, not cosmetics;
   • due: true per memory, with its review_after and source_ref — the store saying a writer dated this claim for a recheck and the date has passed. This is the decay work list; recalls is not (a low count means unproven, never useless — judge the store by the aggregate and never archive a row for being unread);
   • leaked_calls — rows whose text carries a tool call's own source, because a parameter tag was typed without the antml: prefix and the fields after it were written into the body instead of their columns. Per finding: which fields carry a mark, what a repair removes from each, clean: false when the marks sit inside the prose (a reword, not an unleak), and declares — the domain and tags the debris was trying to write, reported only where that column is still empty. So one finding is usually an unleak per dirty field plus the redomain / crosslist / retag that finishes it. stats.leaked_calls counts every one in the window; the list stops at db.LEAK_SCAN_CAP;
   • dedup_hints — pairs probed from the delta against the whole store;
   • domain_hints — spelling/separator/case variants of one domain, cross-window;
   • domain_nesting — flat domains that already spell a hierarchy (acme-x100-p200-cache-warmup → acme/x100/p200/cache-warmup): the raw material for redomain (§2);
   • also per memory — the cross-listings that already hold, so a new one is distinguishable from one already in place;
   • anchors per memory — the verifiable references found in the full body (URLs, file paths, table/field-style identifiers, SNAKE_CASE constants): the list [[memai-confidence]] checks against live facts;
   • truncated: true → page on with offset = offset + count. full=True returns whole bodies (expensive); include_archived=True only when the question is about what was already archived.
5. The state of the work a checkpoint anchors. [[memai-checkpoints]] decides keep/archive against whether that work is still live or already closed, and the store does not know which. That state comes from whatever the host project declares as its source of truth for it — read it once here, so no sub-skill goes looking again. When the project declares none, the pass does not guess: keep the most recent checkpoint per scope, report the rest for the user to rule on, and stage nothing destructive against them.