Store one durable fact, decision, or observation. Use proactively for anything worth keeping — one claim per call. Near-duplicates are dropped, not erred (stored=False, reason="below_surprise_threshold"). For canonical NOW use memory_fact_set.

Args: text: The claim to remember. source: Stable per-project/topic tag for later filtering. tags: Optional labels, e.g. ["decision", "blocker"]. origin: Who asserted it — "user" / "action" / "agent". episode: Episode handle for attribution.

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

Args: query: Natural-language description; specific beats vague. top_k: Max results (default 8). sources / bands / episodes / tags: Optional filters (AND across kinds, OR within list). min_score: Override the 0.25 relevance floor. disable_recency_boost: True to disable recency bias. rerank / bm25: Tri-state overrides; bm25 aids keyword queries, rerank cross-encodes (~200ms). explain: Attach a ranking trace; implies verbose. verbose: Full per-entry metadata; default compact {id, text, source, tags, score} + supersession when set.

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. Optional sources / episodes / tags filters (AND-combined). verbose=True for full per-entry metadata (default entries are compact).

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. Matching is exact-text first, then nearest-embedding fallback — a close paraphrase of old_text works.

Returns: {superseded_count, superseded_texts, new_memory_stored}.

Memory-bank vital signs: per-band sizes, capacities, hit rates, and totals. Use to gauge how much has been remembered or to diagnose why retrieval feels off.

Adjust THIS session's visible toolset, one tier at a time (minimal → core → full; session-scoped, 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 (from search results or a fact's source_entries) 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, case/separator-insensitive. 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.

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.

Args: origin: "user" = human told you; else "action"/"agent" (default). confidence: 0..1, default 0.8. episode: attribution handle. freshness_class: "auto" infers decay from entity kind.

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. accept=true adopts the parked contender as the new current value (old value kept as history); accept=false discards the contender and keeps the current value.

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

With attribute: change history of that canonical fact slot — every version, oldest→newest, each with its writer/session, transaction time, valid time, and age ("what did this used to be? who set it?").

Without attribute: the entity's causal CHAIN — 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.

Args: source_url: http(s) citation URL (any other scheme is rejected). source_quote: The 1–2 sentences the claim was extracted from. freshness_class: evergreen (never decays) | slow (months) | volatile (weeks, default) — sets trust decay at read time. confidence: 0..1 source confidence (default 0.85). retrieved_at / content_hash: Optional fetch time + source hash.

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. verbose=True for full provenance metadata (default entries are compact).

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.

Args: task: Kind of task, stable wording ("deploy engine to host"). outcome: success | failure | correction. about: The tool/approach concerned (aids traversal). detail: What worked / what the dead-end was. polarity: + do-this | - avoid; usually omit (inferred). episode: Episode handle for attribution.

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. verbose=True for full provenance metadata (default entries are compact).

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

Hard-delete from one memory store. Cleanup for junk/test data — no audit trail. For "now wrong, keep history" use memory_fact_set (facts) or memory_supersede (memories) instead.

Scopes: memory: entries matching text / substring / source / episode / tag (at least one; filters OR-combine — ANY match deletes, unlike memory_search's AND). fact: canonical slots — entity required; omit attribute to purge the whole entity. world: world facts — entity (+ optional attribute). lesson: pass the task as entity, the aspect as attribute.

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, up to limit) — read them, write slot-shaped facts via memory_fact_set, then commit. commit: advance the dream cursor to cursor (newest timestamp from the pull). run: one server-side dream with the configured extractor (loop until pulled=0 to drain). deep: full-corpus graph consolidation. Dry-run by default; apply=true snapshots the graph tables first (refuses if it can't). Settle returned candidates via memory_graph_review; snippets=false omits evidence. Also lists lesson/world duplicate slots for hand curation (never auto-deleted).

Returns: per-action dict; {error} on a bad action or missing cursor.

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

Actions: list: pending findings/proposals (optional scope filter). propose: submit link proposals [{src, relation, dst, similarity?, rationale?}] — stored for review, never written directly. dismiss_pair: mark src/dst as genuinely distinct — the pair stops resurfacing as a duplicate candidate. dismiss_slot_pair: same for lesson/world duplicate listings (store; src/dst = listed "entity|attribute" keys). accept_link / reject_link: settle an edge proposal by proposal_id. accept_merge: fold a near-duplicate entity into its twin. accept_junk: delete an over-extraction artifact entity. reject_entity: keep the entity; dismiss its proposal.

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

Open a named sub-episode for a substantial multi-step task. It nests under the auto-managed session episode; memories stored while it is open carry its id + title, enabling episode-scoped search and summaries later. memory_episode_end closes it and pops back to the session.

Returns: {id, title, started_at, parent_id, ...}.

Close the current open episode and pop back to its parent (the session). Returns the closed episode dict, or {} when nothing is open.

Name THIS session's auto-opened episode (default titles are generic). Call once at the start of work — e.g. "Pseudolife-MCP" or "auth-refactor" — 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". Episode ids appear on search/recent results. 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 (topic-driven) or an episode id (session-driven); read the clusters, synthesise one canonical note, then commit it via memory_consolidate.

Args: min_cohesion: Minimum intra-cluster cosine (default 0.6) — raise to flag only near-duplicates.

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

Replace a cluster of near-duplicate memories with one canonical note. Every entry matching replaces (exact text or close paraphrase) 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. Relations come from a closed registry (depends-on, part-of, runs-on, hosts, uses, configures, stores-data-in, related-to); separator variants normalise, and an unknown name is rejected WITH the closest matches — pick one, 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). Pass to for the shortest path between two entities; relation_filter keeps only edges whose relation contains the substring.

Args: depth: Hops from the root (default 1, max 3).

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.

Args: hops: Max graph hops (default 3, max 5). verbose: Full fact/edge provenance (origin, confidence, derivation). Default facts are {attribute, value}, edges {src, relation, dst}.

Returns: {seeds, entities, edges, paths, texts, iterations}.

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. Supports transitive closure (transitive=true) and inverse pairing (inverse_of, like runs-on ↔ hosts); soft src_type/dst_type expectations warn on mismatch but never reject.

Index a file (.txt / .md / .pdf) into the reference bank — a separate store for background documents (papers, manuals, codebases) retrieved by pure cosine similarity, kept apart from conversational memory. source defaults to the filename. path resolves on the SERVER's filesystem — with the Docker daemon, use a path visible inside the container (e.g. a mounted volume), not a host path.

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.