Memory API
Read and update state in session, actor, workflow or global scope.
Operations
memoryChanges
POST /api/v2/memory/changes
Requires: invoke role, worker role
Read the durable namespace change feed after a signed-range sequence cursor. With standalone invoke permission, omit scope to receive authorized global, actor, session and workflow entries; admins see the namespace. Worker-only credentials require an active lease and see only global, inherited actor, bound session and workflow entries. Supply scope and context to restrict further. next_cursor advances across filtered rows up to a consistent snapshot high-water mark. Value sets include value up to 65536 canonical bytes, otherwise value_omitted. Entries older than 30 days are pruned opportunistically; a positive cursor older than retained history returns cursor_expired (409), and a cursor below oldest_sequence means events were pruned and the reader has a gap. Resnapshot and restart with after=0. TTL expiry does not emit an event.
Generated Python client internals: atfgraph._generated.api.memory_api.MemoryApi.memory_changes()
Request body
MemoryChangeQuery (required)
{
"actor_id": "string",
"after": 0,
"lease_token": "string",
"limit": 0,
"prefix": "string",
"root_id": "string",
"scope": "session",
"session_id": "string",
"step_id": "string",
"task_id": "string"
}
Responses
Example response 200
{
"items": [
{
"action": "set",
"created_at": 0,
"key": "string",
"kind": "value",
"principal": "string",
"revision": 0,
"scope": "session",
"scope_id": "string",
"sequence": 0,
"value": {},
"value_omitted": false
}
],
"next_cursor": 0,
"oldest_sequence": 0
}
deleteMemory
POST /api/v2/memory/delete
Requires: invoke role, worker role
Generated Python client internals: atfgraph._generated.api.memory_api.MemoryApi.delete_memory()
Request body
MemoryDelete (required)
{
"key": "string",
"scope": "session"
}
Responses
Example response 200
{
"deleted": false
}
listMemory
POST /api/v2/memory/list
Requires: invoke role, worker role
Page one scope's live keys in ascending key order. scope is required and resolves ownership exactly like memory/read: same id fields, same worker lease authority, same fault codes. Deleted tombstones and expired TTL rows are excluded. kind selects the value or vector store; value entries carry expires_at, vector entries carry dimension. Pass the returned next_cursor back as cursor; a null next_cursor is the last page. Cursors are the last key of the page, so keys inserted before the cursor are not revisited.
Generated Python client internals: atfgraph._generated.api.memory_api.MemoryApi.list_memory()
Request body
MemoryListQuery (required)
{
"scope": "session"
}
Responses
Example response 200
{
"items": [
{
"dimension": 0,
"expires_at": 0,
"key": "string",
"revision": 0,
"updated_at": 0
}
],
"kind": "value",
"next_cursor": "string"
}
readMemory
POST /api/v2/memory/read
Requires: invoke role, worker role
Generated Python client internals: atfgraph._generated.api.memory_api.MemoryApi.read_memory()
Request body
MemoryKey (required)
{
"key": "string",
"scope": "session"
}
Responses
Example response 200
{
"found": false,
"revision": 0,
"value": {}
}
deleteMemoryVector
POST /api/v2/memory/vector/delete
Requires: invoke role, worker role
Tombstone one vector, keeping its revision so later writes never reuse a revision. Returns deleted false when no live vector existed. expected_revision mismatches return revision_conflict (409).
Generated Python client internals: atfgraph._generated.api.memory_api.MemoryApi.delete_memory_vector()
Request body
MemoryVectorDelete (required)
{
"key": "string",
"scope": "session"
}
Responses
Example response 200
{
"deleted": false
}
getMemoryVector
POST /api/v2/memory/vector/get
Requires: invoke role, worker role
Read one stored vector. A missing or tombstoned key returns found false with null embedding and metadata and zero dimension and revision rather than 404.
Generated Python client internals: atfgraph._generated.api.memory_api.MemoryApi.get_memory_vector()
Request body
MemoryVectorKey (required)
{
"key": "string",
"scope": "session"
}
Responses
Example response 200
{
"dimension": 0,
"embedding": [
0.0
],
"found": false,
"key": "string",
"metadata": {
"key": {}
},
"revision": 0
}
searchMemoryVectors
POST /api/v2/memory/vector/search
Requires: invoke role, worker role
Cosine similarity search within one scope. The linear strategy scores source vectors exactly. The hnsw strategy uses migrated PostgreSQL vector indexes and merges source vectors that are not yet backfilled; approximate index recall depends on the corpus. SQLite and PostgreSQL without an applicable index use linear search. Vectors of another dimension are ignored, and scanned reports how many were compared. filters are exact-match on top-level metadata keys under JSON equality (at most 32 keys). Results are ordered by score descending then key ascending and truncated to top_k.
Generated Python client internals: atfgraph._generated.api.memory_api.MemoryApi.search_memory_vectors()
Request body
MemoryVectorSearch (required)
{
"query_embedding": [
0.0
],
"scope": "session"
}
Responses
Example response 200
{
"dimension": 0,
"items": [
{
"key": "string",
"metadata": {
"key": {}
},
"revision": 0,
"score": 0.0
}
],
"scanned": 0,
"strategy": "linear"
}
setMemoryVector
POST /api/v2/memory/vector/set
Requires: invoke role, worker role
Store or replace one embedding under a scoped key. Every element must be a finite number and the norm must be non-zero and at most 1e150; otherwise invalid_vector (400). metadata must be a JSON object of at most 16384 canonical bytes, otherwise invalid_metadata (400). expected_revision is compare-and-set against the live revision (0 means the key must not exist) and mismatches return revision_conflict (409). Revisions never move backwards across a delete.
Generated Python client internals: atfgraph._generated.api.memory_api.MemoryApi.set_memory_vector()
Request body
MemoryVectorWrite (required)
{
"embedding": [
0.0
],
"key": "string",
"scope": "session"
}
Responses
Example response 200
{
"dimension": 0,
"revision": 0
}
writeMemory
POST /api/v2/memory/write
Requires: invoke role, worker role
Generated Python client internals: atfgraph._generated.api.memory_api.MemoryApi.write_memory()
Request body
MemoryWrite (required)
{
"key": "string",
"scope": "session",
"value": {}
}
Responses
Example response 200
{
"expires_at": 0,
"revision": 0
}