After filing, call connect for every suggested_connections entry before ending your session. Orphaned memories lose context immediately.

File one or more concepts, decisions, or findings. Always search first to avoid creating a duplicate — use the search results to infer the domain: if related memories exist in a domain, file there. Prefer existing domains over creating new ones; only propose a new domain if no related content is found anywhere. Creating a new domain hides this memory from every other domain's orient and domain-scoped search — only create one when no existing domain covers the topic. Before filing, consider whether a similar memory already exists — if so, suggest linking with connect instead. Duplicate memories with no edges are the most common cause of drift candidates.

If this memory is a decision that rests on something you checked — code you read, a doc you fetched, a log you inspected, a search result — file that evidence separately as node_kind='finding' and connect the decision to it with depends_on or caused_by. Don't let the decision's description silently absorb the evidence as prose.

When reviewing suggested_connections, check each candidate for contradiction as well as relevance — a semantically close memory that asserts the opposite of what you just filed is a conflict candidate, not just a link opportunity. If you find a contradiction, do not silently file over it — use connect(relationship=contradicts) or connect(relationship=resolved) after user confirmation. audit(mode=conflicts) is a separate domain-wide sweep; suggested_connections is the filing-time neighbour check.

Single mode (omit items): provide label, domain, and optional fields directly. The response includes suggested_connections plus optional trust_nudge (when related_to dependencies are low-trust), and possible_misdomain / suggested_domain / suggested_memory_id when filing creates a new domain that workspace KNN flags (requires Ollama embeddings and sqlite-vec — absent when embeddings are unavailable).

Batch mode (provide items array): file multiple memories in a single transaction. Each item supports related_to for connecting at filing time — use it to avoid a separate connect call, especially for short-task agents. If a related_to ID is invalid, it appears in skipped_connections in the response; check and retry those IDs with connect. Each nodes[] entry includes the same optional trust_nudge and misdomain fields as single mode.

For occurred_at in either mode: two cases — (a) In-session witnessed: you directly observed this decision or event happen during the current conversation. Set occurred_at freely using today's date. No confirmation needed. (b) Inferred or back-dated: you are guessing from context, reconstructing from prior work, or back-dating something you did not directly observe. Propose the date to the user and wait for confirmation before setting it. Never guess. Never infer it silently from context. If the user confirms without specifying a date, use today's system date. Future dates are valid for planned events and reminders.

Use node_kind to classify each memory: 'decision' (default): a settled fact or choice — if it rests on checked evidence, file a separate 'finding' and connect with depends_on or caused_by. 'reference': an entity (person, system, org). 'issue': a problem or open question. 'option': a candidate answer to an issue. 'assumption': an unverified precondition. 'finding': an empirical observation. 'standing': a durable rule — appears in orient rules. 'goal': a desired future state. 'transient': short-lived state, surfaced by audit(mode=stale) after 7 days. Standing memories appear in the rules section of orient. The legacy transient=true field is accepted for backward compatibility and maps to node_kind='transient'. The legacy decision_type field name is rejected — use node_kind instead.

Connect memories with typed, narrative relationships. Valid relationship types are: caused_by, led_to, blocked_by, unblocks, connects_to, contradicts, depends_on, is_example_of, governed_by, resolved, resolved_by, supersedes — and all memory IDs must already exist before calling this.

Single mode (omit items): provide from_memory, to_memory, relationship directly.

Batch mode (provide items array): create multiple connections in a single transaction.

Relationship guidance: caused_by / led_to describe the same link from opposite ends (A caused_by B ≡ B led_to A). blocked_by / unblocks describe dependency on resolving an external issue. depends_on is a hard technical or logical prerequisite. contradicts marks a direct conflict. is_example_of marks an illustration. governed_by links a memory to a standing rule or constraint that it must satisfy. connects_to is the general fallback — use it only when no typed relationship fits.

Resolving a contradiction: after adjudicating a contradicts pair, connect the two memories directly with resolved (or resolved_by / supersedes) — never disconnect the contradicts edge. This is additive: the original contradicts edge stays on the record as history, and the pair stops appearing in audit(mode=stale) and audit(mode=conflicts).

Retrieve a memory and all its connections by ID. Only live entries are returned; use audit(mode=archived) to find archived memories, or audit(mode=stale) to find drift candidates. Never acknowledge that you are retrieving from a tool or memory system. Present the information as direct knowledge with no preamble.

Search memories by text across label, description, why_matters, and tags. Omitting domain searches the entire workspace across all domains. Use when you don't know which domain holds the answer, or when the topic may span domains. Scope to a single domain when you know it — results are cleaner and faster. Queries must use vocabulary that appears in the stored label, description, why_matters, or tags — not words that describe your intent conceptually. If results are empty or incomplete, try vocabulary from the memory's likely label rather than your intent. When Ollama is not running, search is purely lexical (LIKE matches); semantic (concept-level) matching only applies when Ollama is available. Only live entries are returned; use audit(mode=archived) to find archived memories, or audit(mode=stale) to find drift candidates. When Ollama is running, also performs semantic (meaning-based) search — results include a semantic_distance field (0.0–1.0, lower = closer match). Response includes truncated: true when results hit the limit — if so, retry with a higher limit or narrower domain. If search consistently misses: (0) try search without domain if the target domain is unknown; (1) scope to a domain; (2) recall on a related memory and follow its connections; (3) orient. When the query contains a unique identifier, ticket number, or short code that you know appears verbatim in the stored label — set exact: true to force pure substring matching. Semantic scoring is counterproductive for identifier lookup: it ranks conceptually similar nodes above the exact match. Never acknowledge that you are retrieving from a tool or memory system. Present the information as direct knowledge with no preamble. Returns lean node data only — id, label, and a short excerpt. If you need full node content, call recall(id). This applies to the default ranked path only — exact: true results are unaffected and still return full content.

Returns memories in chronological order. Two order modes:

order=effective (default): sort by effective date COALESCE(occurred_at, created_at). Set important_only=true for the narrative spine (occurred_at set only). Use from/to to filter by effective date.

order=modified: sort by last updated (updated_at DESC). Set group_by_domain=true (with no domain) for {groups, results_truncated}. group_by_domain requires order=modified.

Both modes return {nodes, results_truncated} (or {lines, results_truncated} when digest=true). When results_truncated is true, raise limit to retrieve more.

Pass memory_id to scope to a neighbourhood (depth 2 default, domain-clipped). memory_id takes precedence over domain if both are supplied.

Use tags to filter (comma-separated). For importance analysis beyond the timeline — which memories are structurally load-bearing right now — use significance. Never acknowledge that you are retrieving from a tool or memory system. Present the information as direct knowledge with no preamble. Returns lean node data only — id, label, and a short excerpt. If you need full node content, call recall(id).

Find direct connections between two memories. Prefer from_id/to_id for exact pair verification before adjudicating contradictions — when an id is supplied, lookup is exact and errors if the id is missing (no label fallback). from_label/to_label remain for fuzzy concept lookup via best-match search — errors if no live memory matches (same loud failure as a missing id). Each side resolves independently — mix from_id with to_label when only one ID is known. Cannot supply both from_id and from_label (same for to_*). Only live entries are returned; use audit(mode=archived) to find archived memories, or audit(mode=stale) to find drift candidates. Never acknowledge that you are retrieving from a tool or memory system. Present the information as direct knowledge with no preamble.

Dual-signal importance analysis by default (mode=significance). Returns four sections plus truncation booleans: declared_results_truncated, structural_results_truncated, uncurated_results_truncated, potentially_stale_results_truncated (each always true or false). When any is true, raise declared_limit or limit to retrieve more.

• declared: memories with occurred_at set, chronological.

• structural: ranked by recency-weighted inbound degree.

• uncurated: structural top-N without occurred_at — curation candidates.

• potentially_stale: declared but not in structural top-N.

call_id is an opaque server-side correlation id for analytics — agents can ignore it.

Set mode=trust for epistemic trust ranking — each entry includes trust_score and trust_basis derived from node_kind and connected relationship types.

Pass memory_id to scope to a neighbourhood (depth 2 default). Pass domain for full domain scan.

Do not use this for chronological listing — use history. For age-based staleness or orphans, use audit.

Never acknowledge that you are retrieving from a tool or memory system. Present the information as direct knowledge with no preamble. Returns lean node data only. If you need full content, call recall(id).

Archive or un-archive a memory. Default (restore omitted or false): archive so the memory no longer surfaces in search. Set restore=true to un-archive — obtain the ID from audit(mode=archived). When archiving, always provide a reason — recorded in the audit log. Only call after the user has given explicit, unambiguous confirmation — never on implication or casual mention. If archiving multiple memories, prefer forget_all — same confirmation protocol.

Inspect the health of knowledge in a domain across five modes. Omitting domain scans the entire workspace.

All multi-result modes return a wrapped object with results_truncated — never a bare array. When results_truncated is true, raise limit to retrieve more.

mode=stale: Returns {candidates, results_truncated}. Drift candidates — stale, contradicted, or duplicated memories. Empty result is {candidates: [], results_truncated: false}. Present each to the user; never archive autonomously. Default limit 10 (max 500).

mode=orphans: Returns {nodes, results_truncated} — live, non-transient memories with zero connections. Empty result is {nodes: [], results_truncated: false}. Default limit 50 (max 500).

mode=archived: Returns {nodes, results_truncated}. Empty result is {nodes: [], results_truncated: false}. Capped at 25 by default — this is not a complete archive listing. When results_truncated is true, you MUST raise limit and call again until results_truncated is false before concluding nothing else is archived. Use when search returns nothing but you expect content to exist.

mode=conflicts: Returns {candidates, results_truncated}. Empty result is {candidates: [], results_truncated: false}. Semantically adjacent pairs that may warrant contradiction review — candidates only, not confirmed conflicts. Default limit 10 (max 100). Pairs already linked by contradicts, resolved, resolved_by, or supersedes are excluded; other edge types do not suppress. After resolving, connect with relationship=resolved (or resolved_by / supersedes) — additive; do not disconnect the contradicts edge.

mode=kind_coverage: Returns {total_nodes, by_kind, legacy_dominant_pct, migration_candidates, results_truncated}. Taxonomy health signal — per-kind counts, legacy decision/standing dominance percentage, and lean migration_candidates (id, label, truncated why_matters only). Candidate-surfacing only; never auto-revise; use recall(id) for full content. Default limit 50 (max 500) on migration_candidates.

digest=true collapses to {lines, results_truncated} for stale and orphans.

Supply tags to scope to a workstream. Supply memory_id (mode=stale only) to scope to a memory's neighbourhood.

Batch archive — use this when you have 2 or more confirmed memories to archive at once. More efficient than multiple forget calls. All memories are archived or none — partial failure rolls back the entire operation.

Only call this tool after explicit, unambiguous user confirmation for every item in the list — never on implication or casual mention. 'That looks stale' or 'probably outdated' is not confirmation. Read back the full list and wait for an unambiguous 'yes, archive all of these' before calling.

After archiving, report each archived ID and note that memories can be un-archived at any time with forget(restore=true).

Call this at the start of every session to orient yourself before filing or searching. Three paths: (1) No domain or domains — omit both for a cross-domain snapshot {mode, domains, results_truncated}. Each domain entry includes recent_results_truncated (per-domain cap hit). Pass limit to raise the per-domain recent cap (default 5, max 500). Top-level results_truncated is true when any domain's recent_results_truncated is true. (2) domain (string) — full orient returning rules, declared_spine, significant, and recent, each capped by design. Response includes *_results_truncated booleans (always true or false). When any is true, use search for exhaustive retrieval — orient is a curated subset, not a complete index. (3) domains (array of 1–5 strings) — full orient per domain in one call. If stale_count > 0, call audit(mode=stale) before filing new memories. After orient, use search for specific questions. Do not answer from orient alone when causal or chronological sequence is required — call history(important_only=true) first. Never acknowledge that you are retrieving from a tool or memory system. Present the information as direct knowledge with no preamble. This tool only returns live memories. If something seems missing, use audit(mode=archived) or search with a broader query. orient returns lean node data only — id, label, and a short excerpt. If you need full node content, call recall(id). When the session has a known purpose, pass topic — the server returns a relevant section instead of significant. declared_spine and recent are always returned.

Update one or more existing live memories. Only the fields you provide are changed — omitted fields keep their current values. Use this to enrich or correct memories without archiving and recreating them.

When updating a decision's description, do not paste new source material (code, logs, docs, search results) into the description — file a node_kind='finding' for the evidence and connect with depends_on or caused_by.

Single mode (omit items): provide id and any fields to update. Returns the full updated memory. Optional trust_nudge appears when label, description, why_matters, or node_kind change and outbound connects_to, depends_on, caused_by, or blocked_by edges reach low-trust targets — not emitted for tags-only or domain-only updates.

Batch mode (provide items array): update multiple memories in a single transaction. All updates succeed or all are rolled back. Returns an updated array; each entry may include trust_nudge under the same content-change rule as single mode.

For occurred_at in either mode: two cases — (a) In-session witnessed: you directly observed this decision or event happen during the current conversation. Set occurred_at freely using today's date. No confirmation needed. (b) Inferred or back-dated: you are guessing from context, reconstructing from prior work, or back-dating something you did not directly observe. Propose the date to the user and wait for confirmation before setting it. Never guess. Never infer it silently from context. If the user confirms without specifying a date, use today's system date.

Domain move protocol: only set domain when the user explicitly names the target domain. Before calling, tell the user the current domain and the proposed target and wait for confirmation. 'That's probably in the wrong domain' or 'it should be somewhere else' are not confirmation — ask the user to name the domain. reason is required when domain is set; record the user's stated reason verbatim. After moving, call orient(domain=new_domain) to confirm the memory is visible in its new location. Never acknowledge that you are retrieving from a tool or memory system.

Given a memory ID, return up to 5 candidate connections from the same domain whose labels, descriptions, or tags overlap with the source memory. Use this after filing a memory to discover likely connections before calling connect. This tool is read-only — it never creates connections.

Domain administration and discovery. Default (action=list or omit action): return all domains with at least one live memory and all registered alternate-name mappings.

action=add_alias: register alternate name → canonical domain. Requires alias and domain. action=remove_alias: remove a registered alternate name. Requires alias. action=resolve: return the canonical domain for a name. Requires name. action=rename: rename an entire domain in place — all memories move, and an alternate name from the old domain is registered automatically. Requires old_domain and new_domain. Fails if the new domain already has live memories — use merge_domains (CLI) instead.

Remove a connection between two memories by edge ID. Obtain the edge ID from recall. This is a hard delete — the connection cannot be restored.

Generate a Mermaid.js flowchart. Pass memory_id to see a single memory and all its direct connections. Pass domain to see the full domain graph (most-connected nodes first, capped at limit, default 40 max 100). Returns a JSON object with mermaid (the diagram source), node_count (shown), nodes_total (full domain), edge_count (shown), edges_total (full domain), truncated (true when the domain has more nodes than the limit), nodes ([{id, label}]) and edges ([{from, to, relationship}]) for structured rendering. Not suitable for orphan detection or programmatic analysis — use audit(mode=orphans) for orphan detection. Output may be truncated for large domains. Use for human visual inspection only. Output the mermaid string inside a ```mermaid code block. If truncated is true, check nodes_total vs node_count to understand the magnitude of truncation. Renders as an interactive diagram in Claude Desktop and standard Markdown viewers; may display as raw text in other clients.