Memory and state

An agent that forgets everything between turns is a chat box. Orchard gives you two distinct ways to remember, on purpose. There is state, which you declare and your code controls, and there is the memory block, which the model manages on its own. The split matters: state is for the values your program reasons about, and memory is for the things the model decides are worth keeping.

Typed state

A state declaration is a typed, author-declared value that persists across turns and runs. You give it a name, a type, and a default.

state turn_count: int = 0

State is transactional. Writes you make during a turn are buffered and committed at the turn's end. If the turn ends with an uncaught error, the whole buffer is rolled back, so a failed turn leaves no half-written state behind. You read and write it like an ordinary variable:

memory { facts: true }
state turn_count: int = 0

skill remember_city() {
    turn_count += 1                 // typed, persistent; committed at turn end
    remember city = "Wellington"    // free-form durable fact
}

Because state is typed and declared up front, the checker knows its shape everywhere it is used. This is the layer for counters, accumulated results, a workflow's current step: anything your code, not the model, owns.

The memory block

The memory block configures what the runtime persists on the model's behalf, in one embedded store the runtime manages. It has three layers, and you turn on the ones you want.

memory {
    conversation { enabled: true, window: 40 }
    facts: true
    semantic {
        enabled: true
        embeddings { provider: none }
        top_k: 5
    }
}

• conversation persists chat history. With enabled: true the runtime stores each turn and replays the last window messages into context on the next run, so the agent remembers what was said.
• facts turns on the free-form fact layer described below: a durable key/value store the model manages and the runtime digests into every prompt.
• semantic indexes longer-form knowledge for retrieval and pulls the top_k most relevant pieces into context when they are relevant. The embeddings provider chooses how text is scored; provider: none selects the built-in keyword scorer, which works offline and needs no second API key.

The fact layer

Facts are the model-managed counterpart to state. Where state is typed and your code owns it, facts are free-form strings the model writes and reads through a small set of operations. With memory { facts: true } on, these are available both to your code and, as tools, to the model.

• remember k = v stores a value under a key.
• remember v stores a value the runtime keys for you.
• recall(q) returns a map of the facts matching the query.
• recall_one(q) returns a single best-matching value.
• forget k deletes a fact by key.

Because a recall can come back empty, pair it with ??, the default operator, to supply a fallback when nothing matches:

skill recall_city() -> str {
    return recall_one("city") ?? "unknown"
}

This is the layer for things the model learns mid-conversation: a user's stated preference, a name, a constraint they mentioned once. You do not declare these ahead of time because you do not know what they will be.

Knowledge and semantic memory

The knowledge block is how you give an agent a body of reference material up front. Each entry is indexed into semantic memory when the agent loads, and retrieved when it is relevant to the current turn. Entries come in three forms and may repeat.

knowledge {
    text: """
        Research ground rules:
        - Prefer primary sources over secondhand summaries.
        - Note each source's date; flag anything older than two years.
    """
    file: "./handbook.md"
    url: "https://example.com/policy"
}

• text: indexes an inline block of text, good for ground rules and short reference material written right in the file.
• file: indexes the contents of a local file.
• url: fetches and indexes a page.

Knowledge feeds the same semantic layer that remember writes into, so an agent retrieves over both its declared knowledge and anything it later chose to remember. Turning semantic on is what makes that retrieval happen; without it, knowledge is not indexed.

Next. A single agent runs one thing at a time. To fan work out across many spans at once, with budgets shared safely, continue to Concurrency.