io.github.teflon07/memkeeper

List memories in the human-review queue, filtered by review status. Read-only. Use to see what has been proposed via `candidate_submit` and its disposition; approving or rejecting candidates is a human action in the CLI/dashboard.

Queue a proposed memory for human review instead of writing it to recall directly. Mutating: adds an item to the review queue (it does not enter recall until a human approves it via CLI/dashboard). Use this for plausible-but-unverified inferences; use `remember` when the fact is confirmed and should be recallable immediately.

Preview the graph-maintenance pass in dry-run (proposal-only) mode: surfaces the entity and relationship extractions and merges the nightly `dream` job would make, without writing anything. Read-only; no side effects. Use to inspect what graph changes are pending before they are applied.

Search the entity graph by key, canonical name, alias, or type (substring match). Read-only. Returns entity records, not memories — use it to resolve an entity_key or canonical name from a partial term. For memory content use `search`; to traverse outward from a known entity use `graph_neighbors` or `graph_context`.

Create or update one entity in the graph projection (register it, rename it, or add aliases). Mutating. The graph is a rebuildable projection over memories, which remain the source of truth — use this to curate entity identity, not to store facts (use `remember` for facts).

Retire one specific memory by id. Mutating: tombstones the memory (a soft delete that preserves audit history), so it stops surfacing in recall; it is not a hard delete. Set mode='correct' when retiring a memory because it is WRONG (e.g. a surfaced/recalled fact the user contradicted), as opposed to routine cleanup: this records a distinct `correct` event with the memory's provenance, and if you pass corrected_by (the id of the memory holding the right answer) it also records a `contradicts` link. Use mode='correct' for factual corrections so the signal is captured explicitly rather than inferred later.

Fetch one memory by its exact id (for example, an id returned by `search` or `memory_list`). Read-only. Use when you already have the id and want the full record; use `search` to find a memory by its content.

Build a compact, prompt-ready context pack centered on an entity: the entity, its graph neighbors, and the most relevant linked memories, budgeted to a character limit. Read-only. Use when an agent needs ready-to-inject context about one specific entity; use `pack` for query-driven context, or `graph_neighbors` for raw graph edges.

Traverse the entity graph outward from a starting entity, returning connected entities and the relationships between them up to a bounded depth. Read-only. Use to explore how an entity connects to others (raw graph structure); use `graph_context` if you want a prose, prompt-ready context pack instead of edges.

List recent memories in reverse-chronological order for review or cleanup, optionally filtered. Read-only. Use to browse or audit what is stored (including stale or superseded entries); use `search` or `pack` for relevance-ranked retrieval against a query.

Assemble a compact, prompt-ready context block from one or more queries: retrieves, reranks, and budgets the top memories into injectable text. Read-only. This is the retrieval path for putting memory into an agent's prompt; use `search` instead when you want individual scored records rather than an assembled block.

Create or update one directed relationship in the graph: subject --relation_type--> object. Mutating. Identify each endpoint by entity_key (preferred) or internal entity_id. The graph is a rebuildable projection over memories — curate structure here, store facts with `remember`.

Write one durable memory the agent should be able to recall later. Mutating: persists one atomic, self-contained fact, decision, preference, or lesson. When the fact names entities or states a typed relationship, include graph entities, aliases, and relationships in the same call; the memory and graph projection commit atomically and that one memory is the relationship evidence. Do not store secrets or raw transcripts. For a plausible-but-unverified inference, use `candidate_submit`.

Find individual memories ranked by relevance to a query. Semantic-primary when embedding models are loaded, falling back to deterministic BM25/FTS keyword search otherwise; cross-encoder reranked by default. Read-only. Returns scored, individual memory records (with ids) — use this to locate or inspect specific memories. To assemble a prompt-ready context block, use `pack` instead; to browse recent memories without a query, use `memory_list`.

Report store statistics: total/active memory counts, breakdowns by space, silo, status, and kind, schema version, and database size. Read-only; no side effects. Use to inspect the store's overall state and health, not to retrieve memories (use `search` or `pack` for that).

Re-confirm that an existing memory is still accurate as of now, stamping its last-verified time. Mutating: updates verification metadata only — it does NOT change the memory's content or promote it to a durable tier. If the value has CHANGED, do not verify; write a new memory with `remember` and supersede the old one instead.