Build an agent with memory stores

Use memory stores when you need durable context that is usable across users, sessions, and agents and is accessible by outside applications. Memory stores are useful for storing account notes, support playbooks, bug reports, or any content you want to reuse across many agent runs. API Reference:

1. Create the memory store

Create a store for one durable body of knowledge. Use instructions to describe how entries should be written and maintained.

mka1 llm memory-stores create --body '{
  "name": "Acme support memory",
  "description": "Durable support notes for Acme Corp.",
  "instructions": "Keep entries concise. Use one file per durable fact, customer preference, or open issue.",
  "visibility": "workspace",
  "metadata": {
    "account_id": "acct_acme"
  }
}' \
  -H 'X-On-Behalf-Of: <end-user-id>'

import { SDK } from "@meetkai/mka1";

const sdk = new SDK({
  bearerAuth: "Bearer <mka1-api-key>",
});

const store = await sdk.llm.memoryStores.create({
  xOnBehalfOf: "<end-user-id>", // optional — attribute the request to one of your end users
  createMemoryStoreRequest: {
    name: "Acme support memory",
    description: "Durable support notes for Acme Corp.",
    instructions:
      "Keep entries concise. Use one file per durable fact, customer preference, or open issue.",
    visibility: "workspace",
    metadata: {
      account_id: "acct_acme",
    },
  },
});

console.log(store.id);

const storeResponse = await fetch("https://apigw.mka1.com/api/v1/llm/memory_stores", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <mka1-api-key>",
    "X-On-Behalf-Of": "<end-user-id>",
  },
  body: JSON.stringify({
    name: "Acme support memory",
    description: "Durable support notes for Acme Corp.",
    instructions:
      "Keep entries concise. Use one file per durable fact, customer preference, or open issue.",
    visibility: "workspace",
    metadata: {
      account_id: "acct_acme",
    },
  }),
});

const store = await storeResponse.json();
console.log(store.id);

curl https://apigw.mka1.com/api/v1/llm/memory_stores \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "name": "Acme support memory",
    "description": "Durable support notes for Acme Corp.",
    "instructions": "Keep entries concise. Use one file per durable fact, customer preference, or open issue.",
    "visibility": "workspace",
    "metadata": {
      "account_id": "acct_acme"
    }
  }'

The response includes a memory store ID such as mem_store_.... The visibility determines whether this memory store is usable for just a specific X-On-Behalf-Of (private), or whether any user regardless of X-On-Behalf-Of can access it (workspace). See the Create memory store API reference for the full schema.

2. Add memory entries

Entries are addressable by path. Use predictable paths so the agent can find files in the mounted store.

mka1 llm memory-stores create-entry \
  --memory-store-id mem_store_123 \
  --body '{
    "path": "accounts/acme/preferences.md",
    "content": "# Acme preferences\n\n- Prefer concise weekly status summaries.\n- Escalate production incidents to the on-call channel before creating a ticket.",
    "metadata": {
      "kind": "customer-preferences"
    }
  }' \
  -H 'X-On-Behalf-Of: <end-user-id>'

const entry = await sdk.llm.memoryStores.createEntry({
  memoryStoreId: "mem_store_123",
  xOnBehalfOf: "<end-user-id>",
  createMemoryEntryRequest: {
    path: "accounts/acme/preferences.md",
    content:
      "# Acme preferences\n\n- Prefer concise weekly status summaries.\n- Escalate production incidents to the on-call channel before creating a ticket.",
    metadata: {
      kind: "customer-preferences",
    },
  },
});

console.log(entry.id, entry.contentHash);

const entryResponse = await fetch(
  "https://apigw.mka1.com/api/v1/llm/memory_stores/mem_store_123/entries",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: "Bearer <mka1-api-key>",
      "X-On-Behalf-Of": "<end-user-id>",
    },
    body: JSON.stringify({
      path: "accounts/acme/preferences.md",
      content:
        "# Acme preferences\n\n- Prefer concise weekly status summaries.\n- Escalate production incidents to the on-call channel before creating a ticket.",
      metadata: {
        kind: "customer-preferences",
      },
    }),
  },
);

const entry = await entryResponse.json();
console.log(entry.id, entry.content_hash);

curl https://apigw.mka1.com/api/v1/llm/memory_stores/mem_store_123/entries \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "path": "accounts/acme/preferences.md",
    "content": "# Acme preferences\n\n- Prefer concise weekly status summaries.\n- Escalate production incidents to the on-call channel before creating a ticket.",
    "metadata": {
      "kind": "customer-preferences"
    }
  }'

The entry response includes an entry ID and content hash. Save both when your application may update the entry later.

3. Create the saved agent

Create an agent with a shell tool and mount the memory store into the shell environment. The mount object uses:

store_id: the memory store ID to mount
label: the directory name under /mnt/memory
access: read_only or read_write
description and instructions: optional context for how the agent should use the mounted store

Use read_only for reference material. Use read_write only when the agent should be allowed to update memory through the mounted filesystem. When the agent writes, edits, or deletes files inside a read_write mount, the sandbox syncs those changes back to the memory store after the shell command finishes.

mka1 agents create --body '{
  "name": "account-support-agent",
  "description": "Answers support questions with durable account context.",
  "model": "auto",
  "instructions": "Use the mounted Acme support memory for durable account context. Read files under /mnt/memory/acme_support before answering account-specific questions. When you learn a durable Acme fact, write or update the relevant markdown file under /mnt/memory/acme_support. Do not invent account facts that are not present in memory.",
  "tools": [
    {
      "type": "shell",
      "environment": {
        "type": "container_auto",
        "memory_stores": [
          {
            "store_id": "mem_store_123",
            "label": "acme_support",
            "access": "read_write",
            "description": "Durable support notes for Acme Corp.",
            "instructions": "Use these files as account context. Prefer specific files under accounts/acme/. Write durable account learnings back as concise markdown."
          }
        ]
      }
    }
  ],
  "tool_choice": "auto",
  "metadata": {
    "memory_store_id": "mem_store_123",
    "account_id": "acct_acme"
  }
}' \
  -H 'X-On-Behalf-Of: <end-user-id>'

const agent = await sdk.agents.createAgent({
  xOnBehalfOf: "<end-user-id>",
  createAgentRequest: {
    name: "account-support-agent",
    description: "Answers support questions with durable account context.",
    model: "auto",
    instructions:
      "Use the mounted Acme support memory for durable account context. Read files under /mnt/memory/acme_support before answering account-specific questions. When you learn a durable Acme fact, write or update the relevant markdown file under /mnt/memory/acme_support. Do not invent account facts that are not present in memory.",
    tools: [
      {
        type: "shell",
        environment: {
          type: "container_auto",
          memoryStores: [
            {
              storeId: "mem_store_123",
              label: "acme_support",
              access: "read_write",
              description: "Durable support notes for Acme Corp.",
              instructions:
                "Use these files as account context. Prefer specific files under accounts/acme/. Write durable account learnings back as concise markdown.",
            },
          ],
        },
      },
    ],
    toolChoice: "auto",
    metadata: {
      memory_store_id: "mem_store_123",
      account_id: "acct_acme",
    },
  },
});

console.log(agent.id);

const agentResponse = await fetch("https://apigw.mka1.com/api/v1/agents", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <mka1-api-key>",
    "X-On-Behalf-Of": "<end-user-id>",
  },
  body: JSON.stringify({
    name: "account-support-agent",
    description: "Answers support questions with durable account context.",
    model: "auto",
    instructions:
      "Use the mounted Acme support memory for durable account context. Read files under /mnt/memory/acme_support before answering account-specific questions. When you learn a durable Acme fact, write or update the relevant markdown file under /mnt/memory/acme_support. Do not invent account facts that are not present in memory.",
    tools: [
      {
        type: "shell",
        environment: {
          type: "container_auto",
          memory_stores: [
            {
              store_id: "mem_store_123",
              label: "acme_support",
              access: "read_write",
              description: "Durable support notes for Acme Corp.",
              instructions:
                "Use these files as account context. Prefer specific files under accounts/acme/. Write durable account learnings back as concise markdown.",
            },
          ],
        },
      },
    ],
    tool_choice: "auto",
    metadata: {
      memory_store_id: "mem_store_123",
      account_id: "acct_acme",
    },
  }),
});

const agent = await agentResponse.json();
console.log(agent.id);

curl https://apigw.mka1.com/api/v1/agents \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "name": "account-support-agent",
    "description": "Answers support questions with durable account context.",
    "model": "auto",
    "instructions": "Use the mounted Acme support memory for durable account context. Read files under /mnt/memory/acme_support before answering account-specific questions. When you learn a durable Acme fact, write or update the relevant markdown file under /mnt/memory/acme_support. Do not invent account facts that are not present in memory.",
    "tools": [
      {
        "type": "shell",
        "environment": {
          "type": "container_auto",
          "memory_stores": [
            {
              "store_id": "mem_store_123",
              "label": "acme_support",
              "access": "read_write",
              "description": "Durable support notes for Acme Corp.",
              "instructions": "Use these files as account context. Prefer specific files under accounts/acme/. Write durable account learnings back as concise markdown."
            }
          ]
        }
      }
    ],
    "tool_choice": "auto",
    "metadata": {
      "memory_store_id": "mem_store_123",
      "account_id": "acct_acme"
    }
  }'

See the Create an agent API reference for the complete saved agent request shape.

4. Run the agent and update memory

Run the saved agent with the task-specific input. The agent can inspect mounted memory files through the shell tool when it needs durable context. If the mounted store is read_write, the agent can also update memory by writing files under /mnt/memory/<label>. The sandbox restores mounted files before the shell command runs, snapshots them, and syncs changed files back to the store after the command completes.

mka1 agent-runs create \
  --agent-id agt_123 \
  --body '{
    "input": "Draft a support update for Acme about the production incident response plan. Use the mounted Acme memory before answering. Also remember that Acme now wants customer-facing incident summaries by 4 PM Central.",
    "metadata": {
      "memory_store_id": "mem_store_123",
      "source": "docs-recipe"
    }
  }' \
  -H 'X-On-Behalf-Of: <end-user-id>'

const run = await sdk.agentRuns.createAgentRun({
  agentId: "agt_123",
  xOnBehalfOf: "<end-user-id>",
  createAgentRunRequest: {
    input:
      "Draft a support update for Acme about the production incident response plan. Use the mounted Acme memory before answering. Also remember that Acme now wants customer-facing incident summaries by 4 PM Central.",
    metadata: {
      memory_store_id: "mem_store_123",
      source: "docs-recipe",
    },
  },
});

console.log(run.id);

const runResponse = await fetch("https://apigw.mka1.com/api/v1/agents/agt_123/runs", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <mka1-api-key>",
    "X-On-Behalf-Of": "<end-user-id>",
  },
  body: JSON.stringify({
    input:
      "Draft a support update for Acme about the production incident response plan. Use the mounted Acme memory before answering. Also remember that Acme now wants customer-facing incident summaries by 4 PM Central.",
    metadata: {
      memory_store_id: "mem_store_123",
      source: "docs-recipe",
    },
  }),
});

const run = await runResponse.json();
console.log(run.id);

curl https://apigw.mka1.com/api/v1/agents/agt_123/runs \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "input": "Draft a support update for Acme about the production incident response plan. Use the mounted Acme memory before answering. Also remember that Acme now wants customer-facing incident summaries by 4 PM Central.",
    "metadata": {
      "memory_store_id": "mem_store_123",
      "source": "docs-recipe"
    }
  }'

Use Retrieve an agent run to poll status. Use Stream agent run events for live progress. The agent should use the shell tool to read the mounted files and write durable updates directly into the read_write mount.

5. Inspect memory after the run

After the run completes, use the Memory Stores API to inspect what changed. The same files the agent writes in /mnt/memory/acme_support are available as memory entries.

mka1 llm memory-stores list-entries \
  --memory-store-id mem_store_123 \
  --limit 20 \
  -H 'X-On-Behalf-Of: <end-user-id>'

const entries = await sdk.llm.memoryStores.listEntries({
  memoryStoreId: "mem_store_123",
  limit: 20,
  xOnBehalfOf: "<end-user-id>",
});

console.log(entries.data.map((entry) => entry.path));

const entriesResponse = await fetch(
  "https://apigw.mka1.com/api/v1/llm/memory_stores/mem_store_123/entries?limit=20",
  {
    headers: {
      Authorization: "Bearer <mka1-api-key>",
      "X-On-Behalf-Of": "<end-user-id>",
    },
  },
);

const entries = await entriesResponse.json();
console.log(entries.data.map((entry) => entry.path));

curl 'https://apigw.mka1.com/api/v1/llm/memory_stores/mem_store_123/entries?limit=20' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>'

See the List memory entries API reference and Retrieve memory entry API reference for response details.

Operational notes

Use read_only mounts for reference memory and read_write mounts for agents that are trusted to edit durable memory.
Let agents update durable memory by writing files in read_write mounts through the shell tool.
Use direct Memory Stores API updates for seeding, review flows, admin corrections, or imports.
Keep memory entries small enough for the agent to inspect only relevant files during a run.
Use stable path values so your application can map product objects to memory entries.
Store external object IDs in metadata when you need to reconcile memory with your database.
Delete obsolete entries with the Delete memory entry endpoint.

Getting started

Responses

Features

Compute

CLI

Recipes

Benchmarks

Infrastructure

Build an agent with memory stores

1. Create the memory store

2. Add memory entries

3. Create the saved agent

4. Run the agent and update memory

5. Inspect memory after the run

Operational notes

​1. Create the memory store

​2. Add memory entries

​3. Create the saved agent

​4. Run the agent and update memory

​5. Inspect memory after the run

​Operational notes

1. Create the memory store

2. Add memory entries

3. Create the saved agent

4. Run the agent and update memory

5. Inspect memory after the run

Operational notes