Pseudolife Memory

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

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. 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:<project> or claim:<path>), 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.

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.

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

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

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.

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

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.

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

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.

Settle a CONTESTED fact slot after checking with the human. Returns: ``{resolved, accepted, action, current, record}`` or ``{resolved: false, reason: "no_contender"}``.

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

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.

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.

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

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

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.

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

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

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

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

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

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.

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.

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.

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.

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.

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.

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.

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

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.

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

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.

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.

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

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