Skip to Content

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:

MethodEndpointDescription
POST/messagesStore multiple messages
GET/messagesRetrieve messages with optional filtering
GET/sessionsList all session IDs
GET/healthHealth 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 session
  • query_id (optional) - Filter by query
  • limit (optional, default: 100) - Max messages to return
  • offset (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"]}
Last updated on