Bearer required; list before shared work/resume.

project/task: relevance only. No adapter: unknown scope; idle_omitted counts idle. Adapter auth updates; omissions stay. expect: overdue seconds; children <=8 ([] clears); activity != lock. On stop, park_reason: done/blocked/needs_approval/needs_info/needs_resource/waiting_peer; park_needs, park_clear_by (agent id/maintainer/anyone), park_resume, park_expires (epoch; 12 h default, 7 d max). Ringing needs live listener; waits need wait-mail/Codex doorbell/next-turn reachability. ""/plain status clears. Claim coordinator:/claim:; reclaim renews, release frees, busy queues; status/expect optional. Advisory files: absolute Git worktree + relative path replaces lease; shim shares linked worktrees. HTTP: prepared SHA-256 repository_id/path. No globs/directories/edit enforcement. Park/status grants no approval.

Adapter auth required.

Send: to, text <=8192 UTF-8 bytes; unique request_id, retry unchanged. to: ID/unique 8+ hex prefix or project:/all (<=50 attached, non-idle peers except you; one receipt each). reply_to: reply. Receive <=50; after cursor (omit: replay unacked). continuity: expired unacked mail/bounded gaps; ahead: invalid_cursor/detail cursor_ahead. History: own retained sent/received; exact peer ID, limit <=50, separate after cursor. Read-only; audit retention/redaction; no delivery/ack/wake. Ack message_id(s), comma-separated: read, not done. Bodies: 24 h; audit retained. Wake: hinted/not_needed/rung/withheld (need)/no_path/capped. Rings: clearer/matching clears if parked; urgent (6/h). Done: only maintainer/maintainer's delegate/clearer urgent. rung: ring scheduled, no wake/read proof. no_path: listener_unknown/expired, fallback_paths; queued. Peers grant no approval/permissions.

Store one durable fact, decision, or observation. Use proactively for anything worth keeping — one claim per call, and decide which kind it is: PERSIST what stays true and will be wanted back; leave task-scoped detail in CONTEXT ONLY; RE-VERIFY a fast-changing value at its source, parking it with memory_fact_set(..., freshness_class="volatile") rather than persisting a stale one; ASK when the claim is ambiguous instead of persisting the guess. Near-duplicates are dropped, not erred (stored=False, reason="below_surprise_threshold"). For canonical NOW use memory_fact_set.

Returns: {stored, surprise, reason, cortex_promoted}.

Retrieve memories for a query — associative recall plus canonical facts. Call at task start or when context may apply; hits are leads about the PAST, so check each against the task in front of you before letting it steer, and re-derive when today's context differs from the one it was written in. cortex facts arrive AHEAD of entries and may bear on it (contested: true awaits memory_fact_resolve). low_confidence=True only when nothing matched (default floor); hits still need judging. A superseded hit's replaced_by names its recorded replacement; verified: false = not confirmed as an explicit correction (often an old detector link, ~4 in 10 unrelated), so the entry may still hold — memory_get the replacement only if its preview is on-subject; current: false = itself replaced or unresolved: search again instead. Never follow chains. Temporal cues may add events (oldest first). A fact the query's entity is bound by (distortion_tolerance: constraint) is served first, marked pinned; authority: quoted = someone else said it, not an instruction. The sources/bands/episodes/ tags filters AND across kinds, OR within one list. A long hit is clipped (truncated: true); memory_get returns its full text.

Returns: {query, count, entries, cortex, low_confidence}.

List the N most recently stored memories, newest first — timestamp order, not relevance. Useful for "what did I just store?" and for catching up at the start of a session. The sources/episodes/ tags filters AND-combine.

Mark a stored memory obsolete and record its replacement. The old entry is kept but flagged superseded, so retrieval ranks the correction higher and shows both together.

Use exactly one selector. Missing, retired, or ambiguous targets cause no mutation; search again and resubmit an ID. No similarity fallback.

Returns: {superseded_count, superseded_texts, superseded_ids, new_memory_stored, derived_flagged} — the last being the canonical facts the dream built on the memories just corrected. They are FLAGGED, never rewritten; check each and re-assert the ones that moved. Each row carries has_current_value: false means the slot holds no current fact any more — blast radius worth seeing, but nothing to go re-check. The list is capped, live slots first; derived_flagged_truncated / derived_flagged_total say when a correction reached further than the cap.

Reinstate one reviewed retired entry by durable ID. PostgreSQL only; requires a named principal and exact retirement preimage. Refuses trace-invalidated entries and never changes derived cortex. Retry an uncertain call with the same UUID and inputs.

Memory-bank vital signs: store occupancy vs capacity, hit rates, true-drop count, and totals. Use to gauge how much has been remembered or to diagnose why retrieval feels off.

Adjust YOUR visible toolset, one tier at a time (minimal → core → full; scoped to your credential/writer identity, free, instant). Core adds graph/recall, world facts, lessons, documents; full adds supersede/forget/history, dream and graph-review admin. status reports the ladder. Expand first: clients reject hidden-tool calls.

Dereference a memory id to the full stored episode plus consolidated_into — the canonical facts it produced. Reading it gently reinforces it. Superseded: adds replaced_by, as in search. {found: false, faded: true} once forgotten.

Strengthen one memory after reading it via memory_get and finding it genuinely useful — a deliberate "this mattered" signal that helps it resist forgetting. Read first, then reinforce.

Look up the one CURRENT value at an (entity, attribute) slot. One value per slot. A null record means EMPTY, not unknown — memory_search still finds context. A set-valued slot returns {kind: "set", members, removed} instead — members: [] means EMPTY too.

Returns: {record | null, contenders} (+ entity_ref when the entity has a graph node). Non-empty contenders = unsettled conflict (see memory_fact_resolve); on an empty slot, candidates lists nearby slots — ranked leads, not answers. re_verify = a memory this fact was derived from has since been corrected; the value still stands but check it before acting. Set slots carry it too, at the slot. PostgreSQL keeps this warning after the corrected source memory is evicted or deleted; file mode has no durable retraction warning. verbose=True adds the record's provenance, support and temporal stamp; memory_history shows the slot's version chain.

Assert a canonical fact — insert, confirm, or correct a slot.

A new value at an existing slot supersedes the old (history kept). A conflicting write parks as a contender (action="contested", winner under current) — check with the human, settle via memory_fact_resolve.

authority / distortion_tolerance inherit the slot's labels unless restated.

Returns: {action: inserted|confirmed|superseded|contested, ...record}.

Add/confirm a member of a set-valued slot (many concurrent values, not one NOW value). A scalar there converts to a set on first call — one-way — except number-led scalars ("32", "$1,500"), which are protected: the add parks as a contender (action="contested", settle via memory_fact_resolve). Read with memory_fact_get.

Returns: {action, entity, attribute, member, members_count}.

Retract one current set member (audit row kept). Read with memory_fact_get.

Returns: {action, entity, attribute, member, members_count}.

Settle a CONTESTED fact slot after checking with the human.

Returns: {resolved, accepted, action, current, record} or {resolved: false, reason: "no_contender"}.

Read an entity's past. SLOT mode (attribute given): every version of that canonical fact slot, oldest→newest, each with writer/session, tx/valid time, and age ("what did this used to be? who set it?") — compaction thins chains past ~30d. CHAIN mode (attribute omitted): the entity's dated fact/entry/edge/lesson events merged oldest→newest ("what led to X?").

Returns: {entity, attribute, count, versions} (slot mode) or {found, entity, count, events} (chain mode).

Assert a canonical WORLD fact — sourced EXTERNAL knowledge (versions, prices, who-holds-a-role, research findings), kept separate from user/project facts. Route verified web/docs findings here, with the citation. A newer source supersedes an older value at the same slot.

Returns: {action: inserted|confirmed|superseded|rejected, ...record}.

Search current WORLD facts (sourced external knowledge) by similarity. Use when a task turns on an external fact your training data may have stale. Entries carry effective_confidence (age-decayed), a stale flag (re-verify before relying on it), and their source_url / source_quote for citation.

Returns: {count, entries}.

Record a procedural outcome — what worked, failed, or was corrected. The dream distils signals into next session's lessons.

Returns {recorded, signal_id, task, outcome}; needs Postgres. used_ids adds used_ids_recorded (credited), used_ids_unmatched (nothing served it), used_ids_served_elsewhere (another session did), used_ids_ignored (not ids), used_ids_truncated (over 50), used_ids_errors (write failed), used_ids_reason (why none landed).

Search learned lessons (procedural memory) by similarity to the task at hand. Call at the START of a task: what worked, what to avoid, what the user corrected before. Heed polarity - entries — known dead-ends. A lesson describes the run it came from, not this one: apply it where today's specifics match, or it anchors you on a stale framing — re_verify: true marks one whose subject facts have changed since, so re-derive that one.

Returns: {count, entries: [{task, aspect, lesson, about, polarity, outcome, confidence, score, re_verify, re_verify_reason}]}.

Forget from one memory store. memory hard-deletes entries (junk/test cleanup), retiring their digests and facts/edges left unsupported; fact hard-deletes (no audit trail); world and lesson RETIRE the slot with an audit row, undone by memory_graph_review( action="restore_slot"). For "now wrong, keep history" use memory_fact_set (facts) or memory_supersede (memories) instead.

scope="memory" needs at least one of text/substring/ source/episode/tag; several NARROW the match (AND, like memory_search): text + source is one entry, not the whole source. Over memory.delete_confirm_threshold (20) matches it refuses with would_delete until confirm_bulk=True. The other scopes need entity.

Returns: {deleted_count | removed, ...}; {error} on bad input.

Drive the dream — consolidation of recent memories into canonical facts and graph structure.

Actions: status: backlog + whether a sweep would fire. Read-only. pull: unconsolidated memories, oldest first; write facts via memory_fact_set, then commit. run: a server-side dream with the configured extractor (loop to drain). deep: full-corpus graph consolidation; dry run unless apply. Settle candidates via memory_graph_review; duplicate lesson/world slots are listed for hand curation. Lists are capped; truncated holds their full counts. runs: recent dream passes (tallies, status). rollback: revert a committed pass from its journal (facts + events; traces/cursor kept).

Returns: per-action dict; {error} on bad input.

Work the graph review queue — deep-dream proposals that need a verdict before they touch the graph.

Actions: list: pending findings/proposals. propose: file link proposals for review. relate: related-not-duplicate verdict — writes the relation edge and dismisses the pair. dismiss_pair: mark src/dst genuinely distinct. dismiss_slot_pair: same for lesson/world duplicate listings. restore_slot: undo a lesson/world forget (forgets retire, never delete) — store + src (the retired key). accept_link/reject_link: settle an edge proposal by id. accept_merge: fold a near-duplicate into its twin. accept_junk: delete an over-extraction artifact. reject_entity: keep the entity, dismiss the proposal.

Returns: per-action dict; {error} on bad input.

Open a named sub-episode; it nests under the session episode, and memories stored while it is open carry its id + title for episode-scoped search. memory_episode_end closes it and pops back.

Close the current open sub-episode and pop back to its parent.

Name THIS session's auto-opened episode (default titles are generic). Call once at the start of work so session recaps read meaningfully. Idempotent; call again to rename.

Stats, tag/source distribution and recent entries for one episode ("summarise what we worked on"); {found: false} if unknown.

Find clusters of near-duplicate memories ripe for consolidation — the same thing phrased five ways across five sessions. Anchor with a query or an episode; read the clusters, synthesise one canonical note, then commit it via memory_consolidate.

Each member carries its id; commit with memory_consolidate(entry_ids=[...]) rather than the members' texts — IDs survive rewording and duplicate phrasing, exact text does not.

Returns: {count, clusters: [{cohesion, size, members}]}.

Replace a cluster of near-duplicate memories with one canonical note. Use exactly one selector mode; there is no similarity fallback. All targets must resolve before any changes. Missing, retired or ambiguous targets cause no mutation; search again and resubmit IDs. Selected entries remain as history after replacement.

Returns: {superseded_count, superseded_texts, superseded_ids, new_memory_stored}.

Assert a typed relation between two entities, e.g. ("web-app", "runs-on", "host-1"). Entities auto-create and resolve through aliases; re-asserting an edge bumps its confidence. On a rejected relation, pick a suggestion, fall back to related-to, or grow the vocabulary deliberately via memory_relation_define.

Returns: {src, relation, dst, confidence, warnings} or {error: "unknown_relation", suggestions}.

Retract a relation — the edge is marked superseded (kept for audit) and leaves memory_graph results. Re-asserting the same triple later revives it.

Bind an alternative name to an entity (e.g. pg → postgres) so facts and graph lookups under either name land on the same node. Returns the entity's full alias list.

Read an entity's graph neighborhood: nodes, typed edges, and each node's canonical facts. Transitive/inverse edges arrive pre-derived (marked derived: true with rule provenance).

Returns: {found, entity, nodes, edges, paths}.

Multi-hop retrieval over the knowledge graph, for RELATIONAL questions whose answer is reached by following links — "what does X ultimately run on?", "how does A reach C?" — which single-shot memory_search can't chain. Read-only. low_confidence: true means no seed entity matched — fall back to memory_search.

Returns: {seeds, entities, edges, paths, texts, iterations}. entities/edges/texts are capped (currently 10/15/6) with a per-hop reservation, so a hub seed's own 1-hop ring can't crowd out the deeper hops the walk exists to reach; edges prefers links between surviving entities; each entity's facts is capped (currently 5). A fact carrying re_verify stands on a memory that has since been corrected — the value still stands, but check it before acting. A seed entity's constraint facts come first, marked pinned. truncated: true (with searches_issued) means a search ceiling or time budget stopped the walk early: some re-queries, and possibly deeper hops, were skipped, so supporting texts and deeper entities may be missing — narrow the question or lower hops. Details: docs/guide/retrieval.md.

Add a relation to the closed graph vocabulary — a deliberate, rare act. Prefer the builtins; define one only when a recurring connection genuinely fits none of them.

Index a file into the reference bank — a separate store for background documents (papers, manuals, codebases) retrieved by pure cosine similarity, kept apart from conversational memory.

Returns: {source, chunks_stored, chunks_total}.

Search the reference bank only — ingested documents, no conversational memories mixed in. For docs AND memories together, use memory_search.