Memory

Memory shapes a node without adding the same instructions to every prompt. A memory document says what it contains, who owns it, and when it should enter context. The result is durable guidance that can be discovered when relevant instead of a growing startup prompt.

There are two kinds. Knowledge is something an agent consults: a procedure, fact, or technical reference. A preference is behavior the agent should embody: a standing directive or correction. This is a use-based split. A procedure and a fact are both knowledge because the agent reads either one to answer a question; a preference changes how it acts.

| Tier | Owner | Put here | |---|---|---| | Node | One running node | A note needed across that node’s fresh contexts | | Project | One repository or workspace | Repository facts and procedures | | Profile | One application identity and its purview | Application-wide conventions and knowledge | | User | One person | Facts and preferences that follow them everywhere | | Builtin | crouter | Runtime documentation that ships to every user |

Choose the narrowest tier that reaches the next agent who needs the document. For an application author, the profile store is the usual home for knowledge shared by that application’s nodes across repositories. client.memory names a target for every operation, so the daemon resolves the application’s profile rather than its own current directory. A node’s memory:read and memory:write scopes can respectively permit reading while denying changes.

flowchart LR
  Doc[Memory document] --> Surface[Surface entry: event, gate, rung]
  Surface -->|event matches| Preview[Name, preview, or full body]
  Preview --> Route[Routing line tells the agent why to read]
  Route --> Read[Explicit full read when needed]

A surface entry is the delivery mechanism. A document is not loaded because it sits in a particular folder or because its routing line resembles the task. Its frontmatter names an event such as boot, workspace-open, file read, memory read, command, or pre-command; that entry can also match a path or gate on the node’s shape and selects a rung: its name, a preview, or its full content. A document with no surface entry stays in its directory listing until an agent deliberately finds or reads it.

The routing line is the preview at the middle rung, not a trigger. For example, a profile document can have a file-read surface that delivers a preview when an order record is opened. Its line — “When handling a refund request, read this because the eligibility window is not in the order record” — then tells the agent why an explicit full read is useful. The event delivers the preview; the line helps the agent decide whether to read the body without pretending to replace it.

Memory therefore supports progressive disclosure. You can record knowledge freely, but it costs future contexts only when an explicit surface route delivers it. Read crtr memory write -h to author a document and crtr memory read internal/memory-loading for the routing mechanics. The SDK memory page shows how an application creates and revises its profile documents.