ArkMemory

By default, each agent task starts fresh — no knowledge of previous interactions. ArkMemory gives agents durable memory that persists across tasks and pod restarts.

ArkMemory is analogous to a PersistentVolumeClaim: it declares where and how memory is stored, and ArkAgent claims it by name via spec.memoryRef.

How it works

The operator injects memory configuration into agent pods as environment variables. The agent runtime connects to the configured backend before polling the task queue.

During a task, the runtime:

  1. Queries the memory backend for relevant past context and prepends it to the prompt
  2. Writes the task result back to the memory backend after completion

The LLM never calls the memory backend directly — the runtime handles all reads and writes.

Backends

in-context

No external dependency. Memory is carried forward within a single task’s context window only. Once the task ends, the memory is gone.

Use this for stateless agents or when prototyping.

redis

Short-term memory backed by Redis. Entries are stored as key-value pairs and expire via a configurable TTL.

Use this for session-scoped context, recent interaction history, or deduplication state.

apiVersion: arkonis.dev/v1alpha1
kind: ArkMemory
metadata:
  name: research-memory
  namespace: default
spec:
  backend: redis
  redis:
    secretRef:
      name: redis-credentials   # must contain REDIS_URL
    ttlSeconds: 3600
    maxEntries: 500

vector-store

Long-term semantic memory backed by a vector database (Qdrant, Pinecone, or Weaviate). Past results are embedded and stored as vectors. At task start, the runtime performs a similarity search and retrieves the most relevant past context.

Use this when agents need to recall information from days or weeks ago, or when the memory corpus is too large to scan linearly.

apiVersion: arkonis.dev/v1alpha1
kind: ArkMemory
metadata:
  name: research-memory-vector
  namespace: default
spec:
  backend: vector-store
  vectorStore:
    provider: qdrant
    endpoint: http://qdrant.agent-infra.svc.cluster.local:6333
    collection: agent-memories
    secretRef:
      name: qdrant-credentials
    ttlSeconds: 86400

Backend comparison

Backend Best for Notes
in-context Stateless agents, simple tasks No external dependency. Memory lives only within a single task’s context window.
redis Short-term memory, session state Fast reads and writes. Entries expire via TTL.
vector-store Long-term semantic memory, RAG Similarity search across past interactions. Requires a running vector database.

Attaching memory to an agent 

apiVersion: arkonis.dev/v1alpha1
kind: ArkMemory
metadata:
  name: research-memory
  namespace: default
spec:
  backend: redis
  redis:
    secretRef:
      name: redis-credentials
    ttlSeconds: 7200
---
apiVersion: arkonis.dev/v1alpha1
kind: ArkAgent
metadata:
  name: research-agent
  namespace: default
spec:
  model: llama3.2
  systemPrompt: "You are a research agent."
  memoryRef:
    name: research-memory

The same ArkMemory can be referenced by multiple ArkAgent resources in the same namespace.

Spec fields

Top-level

Field Type Required Description
backend string yes in-context, redis, or vector-store
redis RedisMemoryConfig conditional Required when backend is redis
vectorStore VectorStoreMemoryConfig conditional Required when backend is vector-store

redis

Field Default Description
secretRef.name required Secret containing a REDIS_URL key
ttlSeconds 3600 How long entries are retained. 0 = no expiry.
maxEntries 0 (unlimited) Maximum entries per agent instance. Oldest entries evicted when limit is reached.

vectorStore

Field Default Description
provider required qdrant, pinecone, or weaviate
endpoint required Base URL of the vector database
collection agent-memories Collection or index name
secretRef.name no Secret containing a VECTOR_STORE_API_KEY key. Required for hosted providers.
ttlSeconds 0 How long entries are retained. 0 = no expiry.

Environment variables injected

The operator injects these into every agent pod that has a memoryRef:

Variable Description
AGENT_MEMORY_BACKEND in-context, redis, or vector-store
AGENT_MEMORY_REDIS_URL From the referenced Secret
AGENT_MEMORY_REDIS_TTL TTL in seconds
AGENT_MEMORY_REDIS_MAX_ENTRIES Entry cap
AGENT_MEMORY_VECTOR_STORE_PROVIDER qdrant, pinecone, or weaviate
AGENT_MEMORY_VECTOR_STORE_ENDPOINT Base URL
AGENT_MEMORY_VECTOR_STORE_COLLECTION Collection name
AGENT_MEMORY_VECTOR_STORE_API_KEY From the referenced Secret (if set)
AGENT_MEMORY_VECTOR_STORE_TTL TTL in seconds

Failure behavior

If the memory backend is unreachable at pod startup, the agent logs the error and continues without memory. Tasks are not blocked. Memory writes are best-effort and do not affect task delivery guarantees.

See also

Apache 2.0 · ARKONIS