Memory API

Per-agent key-value store, backed by the kernel memory subsystem. Each agent's memory is isolated by construction — the {id} in the path is the only scope, there is no cross-agent read path through this API.

Endpoints

MethodPathActionDescription
GET/agents/{id}/memoryMemoryReadList all KV pairs
GET/agents/{id}/memory/{key}MemoryReadGet a value
PUT/agents/{id}/memory/{key}MemoryWriteSet a value
DELETE/agents/{id}/memory/{key}MemoryWriteDelete a KV pair

MemoryRead/MemoryWrite are admin/operator/developer/service (not viewer, not auditor).

Note: values are stored and returned as strings only — PUT's request body is {"value": "<string>"} (the underlying SetMemoryRequest.value field is a Rust String, not an arbitrary JSON value). Sending a non-string JSON value for value (a bare number, object, array, or boolean) fails body parsing with 422.

GET /agents/{id}/memory

curl -H "Api-Version: v1" -H "Authorization: Bearer hzn_sk_..." \
  http://localhost:4200/agents/550e8400-e29b-41d4-a716-446655440000/memory

Response (200)

{
  "entries": [
    {"key": "claims_processed_count", "value": "142"},
    {"key": "last_claim_number", "value": "CLM-2026-142"}
  ]
}

entries is a list of {key, value} objects, not a {key: value} map.

GET /agents/{id}/memory/{key}

curl -H "Api-Version: v1" -H "Authorization: Bearer hzn_sk_..." \
  http://localhost:4200/agents/550e8400-e29b-41d4-a716-446655440000/memory/claims_processed_count

Response (200)

{"key": "claims_processed_count", "value": "142"}

Response (404)

{"error": {"category": "NotFound", "message": "Key 'nonexistent' not found"}}

PUT /agents/{id}/memory/{key}

Creates the key if it doesn't exist, overwrites if it does.

curl -X PUT -H "Api-Version: v1" -H "Authorization: Bearer hzn_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"value": "5"}' \
  http://localhost:4200/agents/550e8400-e29b-41d4-a716-446655440000/memory/escalation_threshold

Request Body

FieldTypeRequiredDescription
valuestringYesThe value to store — must be a JSON string, not a number/object/array

Response (200)

{"key": "escalation_threshold", "value": "5"}

DELETE /agents/{id}/memory/{key}

Response (204 No Content)

Memory Isolation

Cross-agent memory access at the internal execution layer (not reachable through this HTTP API, which is always scoped by the path's {id}) is rejected with:

{
  "error": {
    "category": "MemoryViolation",
    "message": "Cross-agent memory access denied"
  }
}

MemoryViolation maps to HTTP 503 (memory subsystem considered part of platform health), not 403 — see the error category table.

  • agents.md — the agent this memory scope belongs to