ORGANIZATION MEMORY
What your agents keep, filed where you say¶
An agent that learns something should not keep it to itself. Your organization decides where each kind of record goes and which system holds it, so what one agent writes becomes something the organization knows.
Organization memory is where your agents' records are filed: each kind of record goes on a shelf your organization named, held by a system your organization chose.
This page is for the administrator who sets up where agents' records live.
Agents never choose where their records go. An agent says what kind of record it keeps; your organization answers where that kind is filed, once, for every agent that keeps it.
That keeps the shape of your memory in one place you control, and two agents that keep the same kind of record write to the same shelf.
What is a shelf?¶
A shelf is a place records go, named by a path such as memory/hr/people or
memory/engineering/decisions. A path is the shape of your organization: it
names a kind of record, never a customer, a person or a case, because everybody
who can read this organization's memory can read every path in it.
ekka memory add memory/engineering/decisions --purpose "Architecture decisions our agents record, one per change"
The purpose is shown to whoever reads the list later, usually somebody who was not there when the shelf was named.
How do I give a kind of record a place?¶
An agent declares what its records are about, one word each, such as
decision-record. You answer where that kind goes:
From then on, every decision-record any agent keeps is filed there.
ekka memory subjects lists every answer. A kind with no answer is the usual
reason an agent keeps its records to itself: nothing said where they belong.
Which system holds the records?¶
A shelf says where a kind of record is filed. A binding says which system actually holds it. A plan that names a shelf nothing answers for stops, by name, rather than guessing.
By default a shelf is held by the encrypted store inside your Enclave, on your own machine. That store lists and reads records as a whole; it does not look a record up by a field. If a plan needs to find one record by its email or its id, bind the shelf to a system that can search.
How do I move or remove a shelf?¶
What your agents already wrote stays exactly where it is through every one of these changes.
| To | Run |
|---|---|
| Send a kind of record somewhere else | ekka memory file <kind> <other-shelf> |
| Stop filing a kind of record anywhere | ekka memory unfile <kind> |
| Stop a system answering for a shelf | ekka memory unbind <shelf> |
| Delete a shelf | ekka memory delete <shelf> |
A shelf that still has a kind of record filed on it cannot be deleted, and the refusal names the kind:
ekka memory delete: 'memory/engineering/decisions' is where 'decision-record' is filed. Move them to another shelf first; deleting this one would leave those records with nowhere to go.
Who may read and write memory?¶
An agent reads and writes memory only with a Grant for memory.read,
memory.list or memory.write, like every other capability. Memory is included
in every edition: see Pricing.
Limits¶
- A shelf path names a kind of record. Every member who can read memory can read every path.
- The Enclave's encrypted store reads records whole and does not search by a field.
Every ekka memory command is in the CLI reference.