remember

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.