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 — the current, deduped answer (contested: true awaits memory_fact_resolve). low_confidence=True: no confident match, prefer abstaining. On a superseded entry, prefer superseded_by_text. 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.

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.

Returns: {superseded_count, superseded_texts, 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.

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. Returns {found: false, faded: true} when the episode has since been 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. Its absence is not a guarantee: the flag is read from evidence that still exists, so it stops once the corrected memory is evicted or deleted.

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. Dream synthesises signals into lessons surfaced next session; logging stops repeated mistakes.

Returns: {recorded, signal_id, task, outcome}; needs Postgres.

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 and fact hard-delete (cleanup for junk/test data — 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, and those OR-combine — ANY match deletes, unlike memory_search's AND. 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. 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". Returns {found: false} for an unknown id.

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.

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

Replace a cluster of near-duplicate memories with one canonical note. Every entry matching replaces is marked superseded by new_text, which is stored fresh — the bank gets shorter without losing the audit trail.

Returns: {superseded_count, superseded_texts, 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. 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.