Memory and state — AEL documentation

In AEL, the Agent Engineering Language, state and long-term memory are scoped per tenant, agent, session or subject, with retention and deletion rules. Retrieval (RAG) covers the whole lifecycle of your own documents. Every store is keyed by a trusted tenant identity, never by what a prompt or an input says.

State and memory are different

Kind	What it is	Used for
Run state	The facts a run needs to continue, with a version number.	Checkpoints in the run's storage point, resuming, one owner at a time.
Working context	What the current model call sees.	Building one model request, within its size limit.
Records	What happened in earlier runs.	History you choose to keep.
Long-term memory	Knowledge kept to inform later decisions.	Recall across runs and sessions.
Stored data	Files and media a run produced or received.	References with an expiry and access checks.

Run state is authoritative; memory is not. A run never resumes from something it merely recalled: it resumes from its checkpoint, which only a declared storage point keeps.

Where state, memory and knowledge live

AEL itself contains no database: the memory, knowledge and durable state of your runs live in the storage, database and vector-store packages you select. An agent, subagent or node declares the memory, skills, knowledge, storage and database it uses, each bound to a package you select, and the check refuses any use it did not declare.

Run state and stored data are kept in the run's storage point, the package its agent's storage binding names. A run is durable only when its agent declares a storage point, a storage package you select that keeps the run's state in a directory, in object storage or in an SQL database you run; without one, the run runs to completion and keeps nothing.
Long-term memory is kept by the package that the memory binding names, under the scopes and rules below.
Knowledge is kept by the packages that the knowledge binding names: optional vector-store packages index and search your knowledge for retrieval, in a database you run.

Nothing persists without a declared binding. Bindings and storage describes the record and the storage point.

One handler per state

Each agent's state belongs to one of three domains, which you choose:

Instance: one state for the agent instance, shared by all its runs.
Session: one state per session, such as a conversation.
Request: a fresh state for each request.

Within one domain, one handler runs at a time and changes are applied in turn. Different sessions and requests run at the same time, within the program's limits.

Scopes

Every piece of memory has a scope:

Scope	Visible to
Tenant	The whole tenant.
Agent	One agent, across its sessions.
Session	One conversation or session.
Subject	Everything about one subject, such as a customer, within the tenant.

A scope is bound from the trusted identity of the run, and checked on every read, write, search and subscription.
Sharing a scope needs an explicit grant. Being in the same team of agents, or using the same prompt, shares nothing.
Each scope has its own storage limit, and reading from memory draws on the run's budget.

Retention and deletion

Each scope has retention rules: how long entries live and when they expire.
Deleting an entry removes it from its indexes and caches too.
A deleted entry is never brought back by recovering an older copy.
Every entry records where it came from, when, and which version of the agent wrote it.

Shared memory

Agents in a team can share a memory space, such as a common board of findings, only with explicit grants. Writes are conditional on the version they read, so two agents cannot silently overwrite each other: a conflict goes to a rule you write, which merges the two or rejects one.

Memory is data

What an agent recalls is data, like any other input. It never becomes a credential, a permission or an instruction. A memory entry that says "this user is an administrator" grants nothing.

Knowledge and retrieval

Retrieval (RAG) covers the whole lifecycle: ingest, chunk, embed, index, update and delete, then retrieve with ranking and provenance. You can bring your own knowledge connectors.

You choose whether retrieval is off, runs before a model call or is a tool the model calls.
You choose the store, through the knowledge binding, and the filters, the number of results, the size limit of the retrieved context, freshness rules and what happens when a source is unavailable.
Reading and writing knowledge are separate permissions, and every source is filtered by tenant and access rules.
Retrieved text is evidence, marked with its source and version. It never overwrites the system prompt.
Heavy work such as ingesting and indexing runs on servers, not on small boards.

Retrieval over your documents shows retrieval over your own documents from end to end.

Your own stores

Memory and knowledge are kept by the storage, database and vector-store packages you select, and you write your own connectors for knowledge sources and stores in AEL; they keep the same scopes, limits and access checks. The Package catalog describes the storage, database and vector-store packages.

Tenant identity

Agents are multi-tenant from the start: a trusted tenant identity flows through every call, store, log and reply.

The tenant is set where a request enters, by authentication or by the deployment, never by prompt content.
A field named "tenant" in a request's data is ordinary data. It cannot change the run's tenant.
Sharing data between tenants needs an explicit bridge that you configure, listing what may cross.