Write a memory. type: episode|fact|insight|skill|decision; source: writing agent id; ns: '_shared' or 'agent-'. key: stable id for fact/insight/skill/decision (enables conflict review). Write only stable facts (preferences, conventions, environment constraints, pitfalls), not session-temporary details; volatile status notes (in-progress work, remaining todos) either carry valid_until or stay out — a stale status memory is worse than none; prefer reusing an existing key over a new entry. valid_from/valid_until: optional ISO dates (YYYY-MM-DD) marking the fact's validity window — once valid_until has passed, the memory is excluded from search results but still readable via memory_get. project: optional lowercase-slug scope tag (lowercase alphanumeric segments joined by dashes) for workspace-specific memories — tagged memories are hidden from searches that do not pass the same project, while untagged (global) memories stay visible everywhere; declare your workspace project per the host usage rules and pass it on every write/search in that workspace. lesson_role: optional 'lesson' or 'avoid' (omit for an ordinary memory) — write a lesson as insight (or a steady decision) and an avoid as decision plus this field; do not invent a memory type or encode the role in the key. links may start with avoid:, fixes:, or contradicts: plus a target id or key; other link strings stay free-form. content is capped at 262144 characters — longer payloads are rejected and nothing is written. Returns the stored memory; conflict: true means a different version with the same key exists and a review entry was queued.

Search memories. Fuses lexical (BM25) and, when the vec extra + model are installed, vector (BGE) recall via RRF; otherwise falls back to lexical only. The response always includes retrieval {mode, reason}: mode is vector or lexical, and reason is set when the vector channel is off or the last recall failed (embedder-unavailable, engine-unavailable, or degraded) so a lexical-only fallback is visible without a separate tool. Each hit's 'similarity' field carries the normalized RRF fusion score (fused/rrf_max) in dual-channel mode, or the normalized BM25 score in lexical-only (linear) mode; per-hit rank components and the evidence summary come via explain=true. Confidence/recency/type act only as a small tie-break. Default scope is _shared PLUS your own private 'agent-' namespace (when your identity is known via attested process id or explicit reader) — private hits surface automatically, no extra query needed. Pass ns explicitly ('_shared' or 'agent-') to search a single namespace. project: your workspace project slug — results span global memories plus that project's; omit it and ONLY global (untagged) memories are returned (fail-closed: project memories never leak into general sessions). Each hit embeds up to 3 trimmed one-hop neighbors (active only, project-filtered) unless include_neighbors=False. explain: optional debugging carrier — pass true to attach a per-hit 'explain' object (lexical/vector rank, RRF score, prior term breakdown, retrieval channel) plus an 'evidence' summary line (outcome counts, last_verified, origin); omitted by default so the default hit shape stays unchanged. reader: your own source agent id — REQUIRED when ns is 'agent-' (private namespace, readable only by its owner host). Returns {'hits': [...], 'count', 'retrieval'} sorted by score. Compounding rule: after actually adopting a hit, call memory_feedback (agent = your source id) — skipped feedbacks leave the store static.

Fetch a memory by id; one-hop link neighbors are included by default. reader: your own source agent id — required when the memory lives in a private 'agent-' namespace (readable only by its owner host). project: your workspace project slug — get-by-id itself is always readable regardless of project, but embedded neighbors are filtered to global ones plus your project's. After adopting it, call memory_feedback (agent = your source id).

Create a bidirectional link between two memories (compounding source #2: association). Both memories must live in the same namespace; cross-namespace links are rejected. Memories in a private 'agent-' namespace accept links only from the owner (agent = your own source agent id).

Report feedback on a memory with an outcome (closes the compounding loop — call after actually adopting a memory). Every outcome advances uses and last_used. outcome: 'success' (default, the memory worked), 'failure' (it misled you — confidence drops 0.2, floor 0.05), 'contradiction' (you dispute it — confidence frozen and a review entry is queued pending adjudication), 'obsolete' (it is superseded — archived immediately), 'unknown' (records the event only: confidence does not move). Anything else is rejected. Success raises confidence (+0.1; extra +0.15 when a different agent validates for the first time). agent must be your own source agent id. Memories in a private 'agent-' namespace accept feedback only from the owner (agent = 'agent-' or ''). Archiving is reversed on feedback (except outcome=obsolete, which archives instead).