Memory
A Memory points Ark at an HTTP service that stores conversation history keyed by conversationId / queryId. The CRD is backend-agnostic — any service that implements the Memory HTTP API can back it (a database, queue, or other store). The in-cluster ark-broker is the reference implementation. Queries reference a Memory via spec.memory.name. When unset, the mutating webhook fills it in from ArkConfig/default.spec.defaultMemory if that names a Memory that exists in the query namespace; otherwise resolution falls back at execution time to a Memory named default in the same namespace.
Spec
apiVersion: ark.mckinsey.com/v1alpha1
kind: Memory
metadata:
name: ark-broker
spec:
# --- Required ----------------------------------------------------------
address: # the memory service endpoint (ValueSource)
valueFrom:
serviceRef: # point at an in-cluster service
name: ark-broker
port: "8080"
# value: http://memory.example.com:8080 # OR a direct URL
# --- Optional ----------------------------------------------------------
headers: # HTTP headers sent on every backend request
- name: Authorization
value:
valueFrom:
secretKeyRef:
name: memory-credentials
key: tokenFields
| Field | Type | Required | Description |
|---|---|---|---|
spec.address | ValueSource | yes | The memory service endpoint. Supply a direct value (URL) or a valueFrom source — serviceRef (in-cluster service), configMapKeyRef, secretKeyRef, or queryParameterRef. The resolved value is written back to status.lastResolvedAddress. |
spec.headers[] | list of Header | no | HTTP headers included in every request to the backend. Each entry has a name and a value that is either a direct value or a valueFrom source (configMapKeyRef, secretKeyRef, queryParameterRef). Use for auth tokens or routing headers. |
Address resolution
spec.address is a ValueSource, so the backend endpoint can be a literal URL or resolved from cluster state:
spec:
address:
valueFrom:
serviceRef:
name: ark-broker # resolves to the in-cluster service address
port: "8080"spec:
address:
value: http://memory.example.com:8080 # direct URLThe controller resolves the address and records the result in status.lastResolvedAddress. Consumers (the completions executor, the Query cleanup finalizer) read the resolved address, falling back to spec.address if the status field is empty.
A Memory backed by ark-broker must point at the broker in its own namespace. The broker does not separate data by namespace, so a Memory that reaches another namespace’s broker mixes conversation history across the two namespaces. See Broker storage isolation.
Using memory from a query
A query selects a Memory via spec.memory.name. If a Memory named default exists in the namespace, it is used automatically for queries that don’t name one — unless ArkConfig names a different one (see below). Memory works with all query target types — agents, models, and tools. When a conversationId is provided, messages are persisted to the memory chain regardless of the target type.
Declaring the default for the whole cluster
Set spec.defaultMemory on the cluster-scoped ArkConfig singleton, and the mutating webhook writes spec.memory onto each new query that doesn’t name one:
apiVersion: ark.mckinsey.com/v1alpha1
kind: ArkConfig
metadata:
name: default
spec:
defaultMemory:
name: defaultOnly name is accepted — the Memory is always resolved in the namespace of the query being defaulted. A namespace here would point every tenant at one backend and mix their conversation history, so the validating webhook rejects it.
Three conditions bound the injection:
- The
Memorymust already exist in the query namespace and carry astatus.lastResolvedAddress. Naming one that has not resolved makes queries fail outright, so the webhook skips those namespaces. This is not a safety net for the namedefault: the executor’s own fallback also resolves that name by existence alone, so an unresolvedMemory/defaultfails the namespace’s queries whether or not the field was injected — fix theMemory, don’t rely on the default being skipped. The webhook reads through a cache, so aMemoryand a query applied in the same instant can miss each other; the next query picks it up. - The field is injected at creation only. Updating an older query never back-fills it, so
spec.memoryrecords what that query actually ran with, and changingArkConfigaffects new queries only. - The PostgreSQL storage backend does not serve
ArkConfig. No default is injected there; resolution falls back to theMemorynameddefault.
With the field injected, kubectl get query <name> -o jsonpath='{.spec.memory}' answers which memory a query used without reading executor logs.
Memory in a query to a tool:
apiVersion: ark.mckinsey.com/v1alpha1
kind: Query
metadata:
name: tool-with-memory
spec:
input: "Remember this message for later"
target:
type: tool
name: noop
conversationId: "my-conversation"A follow-up query to an agent on the same conversation ID has access to the tool query’s messages:
apiVersion: ark.mckinsey.com/v1alpha1
kind: Query
metadata:
name: follow-up-agent-query
spec:
input: "What was the last message?"
target:
type: agent
name: my-agent
conversationId: "my-conversation"Memory can also be specified via the CLIs:
# Using fark
fark query --input "Start our conversation" --conversation-id "my-conversation" my-agent
# Using ark
ark query tool/noop "Remember this message for later" --conversation-id "my-conversation"
ark query agent/my-agent "What was the last message?" --conversation-id "my-conversation"Session ID vs Conversation ID:
- sessionId: Groups related queries for tracking and telemetry purposes.
- conversationId: Conversation threading identifier sent to all execution engines as A2A
contextId. The completions engine uses it for memory continuity; named engines can use it for their own session management.
When creating a query in the dashboard it is also possible to specify the memory resource. The dashboard chat window keeps its transcript client-side, and every turn also carries a conversationId: the chat does not set one, but the A2A layer generates a context ID at dispatch and the executor uses that, so a query has one even on a brand-new conversation in a namespace with no memory backend at all.
Telling when memory is not working
A namespace with no Memory degrades rather than failing: resolution falls back to a no-op and queries run without conversation history. A namespace with a Memory that never resolved an address is the harsher case — NewHTTPMemory errors, so those queries fail. The two are worth telling apart, because only the first one is reported on the Query:
| Condition | status: "True" means |
|---|---|
MemoryUnavailable | The query carried a conversationId but no memory backend was reachable, so history was dropped. |
MemoryDegraded | A backend was reachable but reading the history from it failed, so the query ran without prior context. |
Both conditions are written on every query whose dispatch completes, carrying status: "False" and a reassuring message on the healthy path. Read the status field — the presence of the condition says nothing.
kubectl get query <name> -o jsonpath='{.status.conditions[?(@.type=="MemoryUnavailable")]}'Two limits on that signal, both of which the ark status check below exists to cover:
- A query that failed to dispatch carries neither condition. An unresolved
Memoryis exactly that case: the query errors withfailed to create memory client, and no memory condition is written. MemoryUnavailablerequires aconversationId, since it means “continuity was expected and not delivered”. Every dashboard chat turn has one — the A2A layer generates a context ID at dispatch even when the chat supplies none — so this covers a namespace that never had a memory backend as well as one that lost it.
Two surfaces read this for you:
- Dashboard chat shows a notice at the top of the conversation when the last turn reported either condition as
True, quoting the condition’s own message. ark statusprints adefault memoryline for the kubeconfig’s current namespace, and it asks the namespace directly rather than reading conditions. It reports the namespace as broken when it has a broker but noMemory, and when aMemoryexists but never resolved an address. A broker counts when it has published an enabledark-config-broker/ark-config-streamingConfigMap, or failing that when a Service carrying the broker chart’s label is present — those ConfigMaps are optional, so their absence alone is not proof there is no broker. A namespace with no broker is reported as unconfigured rather than broken. What it cannot read, it does not guess at: an unlistable ConfigMap is always undetermined, and a forbidden cluster-scopedArkConfigdowngrades a broken verdict to undetermined rather than accusing the namespace of a fault that a default it cannot see may already rule out. The line is informational: it does not change the command’s exit code.
Memory HTTP API
A memory backend is an HTTP server implementing the following endpoints. The ark-broker is the reference implementation; the Ark API gateway proxies the same contract.
| Method | Endpoint | Description |
|---|---|---|
| POST | /conversations | Create a new conversation |
| GET | /conversations | List all conversation IDs |
| GET | /conversations/{id} | Get conversation details and messages |
| DELETE | /conversations/{id} | Delete a specific conversation |
| POST | /messages | Store messages (requires conversation_id) |
| GET | /messages | Retrieve messages with optional filtering |
| DELETE | /queries/{queryId}/messages | Delete all messages for a query across all conversations |
| GET | /health | Health check |
Create Conversation
POST /conversations
Creates a new conversation and returns its ID. This must be called before storing messages.
Response:
{
"conversation_id": "550e8400-e29b-41d4-a716-446655440000"
}Store Messages
POST /messages
Stores messages for an existing conversation. The conversation_id is required.
{
"conversation_id": "550e8400-e29b-41d4-a716-446655440000",
"query_id": "query-uuid",
"ttl_seconds": 2592000,
"messages": [
{
"role": "user",
"content": "What is the weather like?"
},
{
"role": "assistant",
"content": "I don't have access to real-time weather data."
}
]
}ttl_seconds (optional) sets a per-message expiry: each stored message is stamped with an expires_at snapshot and filtered out on read once it elapses. This expires messages on a timer — it does not delete them; see Delete Query Messages for explicit removal. When omitted, the backend applies its default visibility TTL.
Get Conversation
GET /conversations/{id}
Returns conversation details including all messages:
{
"conversation_id": "550e8400-e29b-41d4-a716-446655440000",
"messages": [
{
"timestamp": "2024-01-01T12:00:00Z",
"conversation_id": "550e8400-e29b-41d4-a716-446655440000",
"query_id": "query-uuid",
"message": { "role": "user", "content": "Hello" },
"sequence": 1
}
]
}Retrieve Messages
GET /messages?conversation_id={id}&query_id={id}&limit={n}&offset={n}
Retrieves stored conversation messages:
conversation_id(optional) - Filter by conversationquery_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",
"conversation_id": "conv-abc123",
"query_id": "query-uuid",
"message": {
"role": "user",
"content": "What is the weather like?"
}
}
],
"total": 100,
"limit": 50,
"offset": 0
}List Conversations
GET /conversations
Returns object with conversation IDs:
{"conversations": ["conv-1", "conv-2", "conv-3"]}Delete Query Messages
DELETE /queries/{queryId}/messages
Hard-deletes all messages for a query across every conversation. The Ark controller calls this to clean up broker state when a Query is deleted — see Query → Deletion and cleanup. The operation is idempotent.
Response:
{
"status": "success",
"message": "Query <queryId> messages deleted"
}A backend that does not implement this endpoint should return 404 or 405; the controller treats both as “not supported” and skips cleanup.
Status
status:
phase: ready
lastResolvedAddress: http://ark-broker.default.svc.cluster.local:8080
message: Memory backend reachableStatus fields
| Field | Description |
|---|---|
status.phase | One of running, ready, error. |
status.lastResolvedAddress | Last resolved value of spec.address, kept for reference. Consumers read this first, falling back to spec.address. |
status.message | Additional information about the current status (e.g. a resolution or reachability error). |
Print columns
kubectl get memories prints NAME, PHASE (.status.phase), ADDRESS (.status.lastResolvedAddress), and AGE.
Related
- Query — references a
Memoryviaspec.memory. - Broker Service — the reference memory backend and its HTTP API.
- Ark API — gateway that proxies the memory contract.