Memory API

Per-agent key-value store. Each agent has an isolated memory scope.

Endpoints

GET /agents/{id}/memory

List all key-value pairs for an agent.

curl http://localhost:4200/agents/550e8400-e29b-41d4-a716-446655440000/memory

Response (200)

{
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "entries": {
    "claims_processed_count": 142,
    "avg_processing_time_ms": 3200,
    "last_claim_number": "CLM-2026-142",
    "escalation_count": 7
  }
}

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

Get a specific value.

curl 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 in agent memory"
  }
}

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

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

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

Request Body

{"value": 5}

Values can be any JSON type: string, number, boolean, object, array.

Response (200)

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

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

curl -X DELETE http://localhost:4200/agents/550e8400-e29b-41d4-a716-446655440000/memory/notes

Response (204 No Content)

Memory Isolation

Each agent's memory is scoped. Attempting to access another agent's memory through this API is not possible — the agent ID in the path determines the scope.

In the internal execution layer, cross-agent memory access returns:

{
  "error": {
    "category": "MemoryViolation",
    "message": "Cross-agent memory access denied",
    "details": {"caller": "agent-a", "scope_owner": "agent-b"}
  }
}