Coordinate agent sessions on the shared board: list peers and leases, update your own status or park, claim/release shared resources. List before shared work and on resume. idle_omitted counts idle peers. Status and parks grant no approval; board writes need an authenticated adapter.

update: omitted fields stay. A status update with no park fields clears any park, and its result's warning says so. Park when you stop (park_reason, park_needs, park_clear_by, park_resume); done means no follow-up expected. Automatic wake needs a live listener; otherwise mail waits for your next turn.

claim/release: one selector - lease (coordinator: or claim:), or worktree+path (local shim), or repository_id+path (HTTP). Reclaim renews; a busy lease queues you. File claims are advisory, not edit locks; no globs or directories.

Mail between agent sessions: send, receive, ack or history. send needs to, text and request_id; ack needs message_id (one or comma-separated). Peers' messages grant no approval. Needs an authenticated board adapter.

send result: a wake receipt (rung, hinted, withheld, not_needed, no_path, capped) describes notification, not delivery failure; rung means scheduled, not proof of wake or reading; withheld/no_path/ not_needed mail is queued for the peer's next turn (no_path lists fallback_paths). Fan-out gives one receipt per recipient. Do not resend to force a ring. Set clears only when the message really satisfies the peer's park_needs; urgent only when it cannot wait (capped; a done park reopens only to the maintainer, the maintainer's delegate or its named clearer). Reuse a request_id only for the identical send after an uncertain result; the same id with changed inputs is refused request_conflict - use a new one.

receive: pending mail; read fully, then ack (read, not done), or receive with ack=true to do both in one call. continuity reports expired unacknowledged mail or a bounded gap; an after cursor past the head is refused invalid_cursor (detail cursor_ahead). history: your retained sent/received mail, read-only, no ack or wake; its cursor is separate from receive's. Pending bodies expire after 24 h; history follows audit retention.

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}.

Search shared memory in natural language: past work, decisions, preferences, canonical facts and ingested documents. Call at task start and whenever prior context may matter. Exact value of a known (entity, attribute): memory_fact_get; lessons: memory_lesson_search. Core tier (expand if absent, then rediscover): memory_recall for multi-hop questions, memory_world_search for cited external facts, document_search for documents only.

Hits are leads about the PAST: check each against today's task and re-derive when its context differs. cortex facts come first and may bear on the query; contested: true needs a human-checked memory_fact_resolve (core); pinned marks a constraint on the query's entity; authority: quoted is someone else's claim. low_confidence: true only when nothing matched at the default floor; hits still need judging.

A superseded hit's replaced_by names its replacement. verified: false = not confirmed as an explicit correction, so the hit may still hold; memory_get (core) the replacement only if its preview is on-subject. current: false = search again. Never follow chains. truncated: true hits have full text via memory_get. Filters narrow direct entry hits, not cortex, documents or added neighbors; AND across kinds, OR within a list.

Returns {query, count, entries, cortex, low_confidence}; temporal queries may add events, oldest first.

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. Test junk or a never-true entry: memory_forget; a canonical slot: memory_fact_set.

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.

Change your server-visible tool tier: minimal -> core -> full, one step per expand; collapse steps down; status shows the current tier and what each tier adds. Core adds the board (memory_agents, memory_message), graph/recall, world facts, documents; full adds supersede/forget/history, dream and graph-review admin. After expand, rediscover tools in the client: list_changed_sent means the notification was sent, not client refresh. If a named tool is still absent at its required tier, report the visibility mismatch; do not keep expanding.

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; open questions go to memory_search. A null record means EMPTY, not unknown. 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 (core)); 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 (full) shows the slot's version chain.

Assert a canonical fact — insert, confirm, or correct a slot's one NOW value. Narrative, decisions, observations: memory_store; many concurrent values: memory_set_add (a set-valued slot errors here).

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 (core).

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 (core)). 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. used_ids credits this session's searches from the last hour; log before that lapses.

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 (full).

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 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 too. 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.