Memory
The Memory
resource represents persistent storage for converations with agents. It is designed to be agnostic of the backend implementation, meaning that a database, queue or other system can be used.
The backend for a memory resource is an HTTP server that implements the Memory API Specification.
In time, this resource will also configure how operations such as compaction can be performed. A reference implementation ARK Cluster Memory is available.
Specification
apiVersion: ark.mckinsey.com/v1alpha1
kind: Memory
metadata:
name: ark-cluster-memory
spec:
# The address of the service that handles memory API calls.
address:
# A 'value' can be provided to give a specific URL, or a service ref to
# point to a specific service in the cluster.
valueFrom:
# In this example, we point to a deployment of the "ARK Cluster Memory".
serviceRef:
name: ark-cluster-memory
port: 8080
Usage
Memory can be specified in a query resource. If a Memory resource named default
exists in the namespace, it will be automatically selected for queries that don’t explicitly specify a memory.
Memory in a query resource:
apiVersion: ark.mckinsey.com/v1alpha1
kind: Query
metadata:
name: chat-with-memory
spec:
input: "What did we discuss earlier?"
targets:
- name: my-agent
memory:
name: ark-cluster-memory
# Optional: specify session ID to group related queries
# If not provided, the query UID is used as the session identifier
sessionId: "my-conversation-session"
Memory can also be specified via the fark
CLI:
fark query --input "Continue our conversation" --session-id "my-conversation-session" my-agent
When creating a query in the dashboard it is also possible to specify the memory resource. Note that in the dashbhoard ‘chat’ window, no memory is used, messages are simply stored client-side as is common for chat applications.
Memory API Specification
Memory is implemented as a simple HTTP server:
Method | Endpoint | Description |
---|---|---|
POST | /messages | Store multiple messages |
GET | /messages | Retrieve messages with optional filtering |
GET | /sessions | List all session IDs |
GET | /health | Health check |
Store Messages
POST /messages
Request body includes session/query context and message array:
{
"session_id": "uuid-string",
"query_id": "query-uuid",
"messages": [
{
"role": "user",
"content": "What is the weather like?"
},
{
"role": "assistant",
"content": "I don't have access to real-time weather data."
}
]
}
Retrieve Messages
GET /messages?session_id={id}&query_id={id}&limit={n}&offset={n}
Retrieves stored conversation messages:
session_id
(optional) - Filter by sessionquery_id
(optional) - Filter by querylimit
(optional, default: 100) - Max messages to returnoffset
(optional, default: 0) - Skip messages for pagination
Returns timestamped message records:
{
"messages": [
{
"timestamp": "2024-01-01T12:00:00Z",
"session_id": "uuid-string",
"query_id": "query-uuid",
"message": {
"role": "user",
"content": "What is the weather like?"
}
}
],
"total": 100,
"limit": 50,
"offset": 0
}
List Sessions
GET /sessions
Returns object with session IDs:
{"sessions": ["session-1", "session-2", "session-3"]}