remember
File concepts, decisions, and findings as persistent memories with typed relationships, enabling retrieval by association rather than address.
Instructions
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. Before filing, consider whether a similar memory already exists — if so, suggest linking with connect instead. Duplicate nodes with no edges are the most common cause of drift candidates.
Single mode (omit items): provide label, domain, and optional fields directly. The response includes a suggested_connections field.
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.
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 decision_type to classify each memory: 'decision' (default) for facts and findings, 'transient' for short-lived state like ticket notes that will stale within days, 'standing' for durable rules and constraints that govern other memories. Transient memories older than 7 days are surfaced by audit(mode=stale) as archiving candidates. Standing memories appear in the rules section of orient. The legacy transient=true field is accepted for backward compatibility and maps to decision_type='transient'.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| decision_type | No | Classify this memory. 'decision' (default): a fact, finding, or decision. 'transient': short-lived state (ticket notes, sprint state) — surfaced by audit(mode=stale) after 7 days. 'standing': a durable rule or constraint that governs other memories — appears in the rules section of orient. | |
| description | No | What this memory is about | |
| domain | No | The domain or project this belongs to (e.g. 'deep-game', 'sedex', 'general'). Required in single mode; omit when using items. | |
| items | No | Batch mode: array of memory objects to file in a single transaction. Each must have label (string, required) and domain (string, required). Optional: description, why_matters, tags (space-separated keywords), occurred_at (ISO8601 — in-session: set freely; inferred/back-dated: propose+confirm, never infer silently), decision_type (string: decision|transient|standing), transient (boolean, deprecated — maps to decision_type=transient), related_to (string ID, object with id+relationship, or array of either — connects at filing time; invalid IDs appear in skipped_connections). | |
| label | No | Short name for this memory (e.g. 'RST $10 boot crash'). Required in single mode; omit when using items. | |
| occurred_at | No | ISO8601 date or datetime. (a) In-session witnessed: you directly observed this happen in the current conversation — set freely using today's date, no confirmation needed. (b) Inferred or back-dated: you are guessing or reconstructing — propose to user and wait for confirmation. Never guess. Never infer silently. Single mode only. | |
| related_to | No | Optional list of memories to auto-connect at creation time. Single mode only. Each item is either a plain memory ID string (creates a connects_to connection) or an object with id and relationship fields. Invalid or unknown IDs are silently skipped. | |
| tags | No | Space-separated synonyms and keywords that improve search recall. Examples: 'testing gradle kotlin approval'. These are searched alongside label, description, and why_matters. Populate this with alternative terms an agent might use to find this memory later. | |
| transient | No | Deprecated — use decision_type='transient' instead. Accepted for backward compatibility: if true and decision_type is not set, maps to decision_type='transient'. | |
| why_matters | No | Why this is significant - the 'so what' |