Memory
The Memory screen lets you read, add, search and delete the long term memory items that agents write during their
runs. Portal path: /data/memory. Developers use it to check what an agent remembers; tenant administrators use it to
remove an item on request.
What the screen shows
The Memory items table lists the items you can read: the server keeps only the items that are not deleted, not
expired, whose readers ACL holds one of your identities and whose classification does not exceed your clearance.
Columns: Scope type, Scope id, Kind, Content, Classification, Expires.
Filters above the table: Scope type (user, agent, session, project, tenant), Scope id and Kind
(fact, preference, summary, episode), applied with Filter.
A click on a row opens a drawer that loads the item with its version history (history).
The creation form New memory item has Scope type (required), Scope id (required), Kind (required),
Content (required), Classification (internal, public, confidential, restricted), Subject id and
TTL (days). The portal sends the TTL as ttl_seconds (days x 86400).
Under the table, the Search memory tester has Query (required), Scope type, Scope id, Kind and Top K (10). The scope is sent only when both its type and its id are filled.
Actions
| Button or action | What it does | API call | Roles |
|---|---|---|---|
| Refresh icon, Filter | Reloads the list with the filters | GET /v1/memory | any tenant user (ACL filtered) |
| New memory item > Create | Writes an item; the DLP may raise its classification | POST /v1/memory | any tenant user, within the policy and the clearance |
| Click on a row | Opens the item and its history | GET /v1/memory/{memory_id} | readers ACL |
| Delete (row menu) | Shows the impact confirmation, then erases the content, the vector and the versions | DELETE /v1/memory/{memory_id} | writers or owners ACL, or tenant_admin |
| Run (Search memory) | Semantic search across the items | POST /v1/memory/search | any tenant user, within the policy |
Roles
The portal hides no button on this screen. In services/control-plane/src/eai/domains/memory/__init__.py the
Control Plane checks the ACL of each item rather than a role: an item created from the portal gets your identity as
reader, writer and owner. Writing goes through the policy decision memory.write and is refused when the
classification exceeds your clearance. Deleting needs the writers or owners ACL, or tenant_admin; an item held
by a legal hold cannot be deleted, and an item marked not deletable is deleted only by tenant_admin.
Typical tasks
Check what an agent remembers
-
Filter on the agent. Memory is stored per scope. Choose Scope type
agent, type the agent id in Scope id, then click Filter.Expected result: the items of this agent with their Kind and Expires date.
If it fails: an empty table means no item is visible to you; your identity must be in the
readersof the items. -
Open an item. Click the row.
Expected result: the drawer shows the item, its ACL, its
deletionblock and itshistory.If it fails:
not_foundmeans the item expired, was deleted or is above your clearance.
Find a memory by meaning
-
Run a search. The search is semantic, not a text match. In Search memory, type a Query, optionally a scope, then Run.
Expected result: the closest items in the result panel.
If it fails:
policy_deniedmeans the policy refuses the search for this scope.
Delete an item on request
-
Delete it. Deletion removes the content, the vector and the old versions. Open the row menu, choose Delete and confirm.
Expected result: the toast "Done" and the row disappears.
If it fails:
legal_hold(409) means a legal hold protects it; see Retention.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
invalid_request (400) with kind on Create | The server accepts the kinds episodic, semantic, procedural, preference, fact; the portal list also offers summary and episode | Choose fact or preference |
invalid_request (400) with scope | Unknown scope type | Use session, agent, user, project or tenant |
policy_denied (403) on Create | The classification (possibly raised by the DLP) exceeds your clearance, or the policy refuses the write | Lower the classification or ask for a higher clearance |
not_permitted_acl (403) on Delete | You are not in the writers or owners of the item | Ask its owner or a tenant administrator |
legal_hold (409) on Delete | A legal hold covers the item | Release the hold first in Retention > Legal hold |
conflict (409) on Delete | The item is marked not deletable | A tenant_admin deletes it |