Distill durable facts from text and write them to a namespace's memory.

The raw text is NOT stored verbatim: an extraction pass distills it into discrete facts, which are embedded and indexed for memory_search. Returns how many facts were written (possibly 0 if nothing extractable). Additive only — never overwrites or deletes existing facts; contradictions are handled by supersession, with full history retained. Creates the namespace on first write.

Use it after learning durable information worth recalling in later sessions (preferences, decisions, biographical facts) — not for transient chatter, and not to re-state facts already in memory (use memory_search to check what is already known; use memory_clear to delete a namespace). With the [extract]/[models] extras installed, the first call in a fresh environment downloads model weights (one-time, can take minutes); the call blocks until done.

Retrieve the facts most relevant to a query from a namespace's memory.

Read-only with respect to memory content: it never modifies or deletes stored facts (searching a namespace that does not exist yet returns "No facts found.", though the empty store file is created as a side effect). Returns up to k facts as a bulleted list, deduplicated, most relevant first.

Use it before answering anything that may depend on prior context — preferences, past decisions, earlier sessions. Facts only exist here if something wrote them via memory_add; memory_clear deletes a whole namespace. With the [models] extra installed, the first call in a fresh environment downloads model weights (one-time); the call blocks until done.

Delete ALL memory for a namespace by removing its SQLite file. Irreversible.

Use only when the namespace's entire history should be forgotten; there is no per-fact deletion. Idempotent — clearing a missing namespace succeeds as a no-op. Other namespaces are untouched.

Refuses (returns an explanatory message, changing nothing) while a LIVE maintenance lease with a fresh heartbeat is held for the namespace (spec §7.3): a POSIX unlink cannot safely interrupt an in-flight maintenance run — the run's open handle would keep committing to the unlinked (ghost) inode, silently losing that work. So clear waits for the run to finish or its lease to go stale. A stale or absent lease clears normally; the maintenance runner itself independently skips a namespace cleared mid-run at its next batch boundary.

Residual race (spec §7.3, known limitation): a clear that lands in the sliver BETWEEN this lease-check and the unlink is not prevented — full cross-process file locking is deliberately out of scope for v1. The two guards (this refusal + the runner's batch-boundary skip) shrink the window; they do not close it.

Run one sleep-time maintenance pass on a namespace (§6.3).

DRY-RUN by default (apply=False): computes the full would-do report with ZERO writes — no ledger row, no proposals. apply=True claims the lease, runs the provably-safe auto band (exact-dup retirement + auto-band eviction) AND stages the judgment-call proposals for human review. Symmetric with lean-memory-maintain. NOTE the asymmetry with the LM_MAINT_AUTO auto-spawn path: that fires --apply --auto-only (auto band only, never stages proposals), so unattended runs cannot grow the review queue — only interactive apply=True stages.

Returns the run summary: mode, staged/merged/demoted counts, and threshold stats.

Report a namespace's maintenance ledger — runs + pending proposals (§6.3).

MODEL-FREE by contract: this reads the namespace DB directly and NEVER builds the embedder/reranker (it does not call _mem()). Answering "when did maintenance last run?" must never trigger the ~2 GB first-run model download.

List pending maintenance proposals, grouped by entity, with evidence (§6.3).

Each group carries the subject entity and its proposals; each proposal includes its parsed payload (the evidence) so a reviewer sees what would change. Not fully read-only: overdue proposals lazily expire (are marked expired) as a side effect of listing. Returns a JSON string (the grouped list). Use memory_review_decide to act on a listed proposal.

Decide a maintenance proposal: approve | reject | edit | promote (§6.3).

approve applies the proposal's verbs at decide-time (with apply-time target re-validation); reject leaves the spine byte-identical; edit (summarize only) approves the human-edited text; promote (evict only) rejects the eviction and lifts the fact back to the hot tier. Returns a JSON result string.