> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mka1.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Build an agent with memory stores

> Mount durable memory into a saved agent's managed shell environment and keep it current between runs.

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:

* [Memory Stores endpoints](/api-reference/memory-stores/create-memory-store)
* [Memory Store entry endpoints](/api-reference/memory-stores/create-memory-entry)
* [Agents collection and run endpoints](/api-reference/agents/create-an-agent)

## 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.

<CodeGroup>
  ```bash CLI theme={null}
  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>'
  ```

  ```ts MKA1 SDK theme={null}
  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);
  ```

  ```ts fetch theme={null}
  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);
  ```

  ```bash bash theme={null}
  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"
      }
    }'
  ```
</CodeGroup>

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](/api-reference/memory-stores/create-memory-store) 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.

<CodeGroup>
  ```bash CLI theme={null}
  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>'
  ```

  ```ts MKA1 SDK theme={null}
  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);
  ```

  ```ts fetch theme={null}
  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);
  ```

  ```bash bash theme={null}
  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"
      }
    }'
  ```
</CodeGroup>

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.

<CodeGroup>
  ```bash CLI theme={null}
  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>'
  ```

  ```ts MKA1 SDK theme={null}
  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);
  ```

  ```ts fetch theme={null}
  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);
  ```

  ```bash bash theme={null}
  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"
      }
    }'
  ```
</CodeGroup>

See the [Create an agent API reference](/api-reference/agents/create-an-agent) 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.

<CodeGroup>
  ```bash CLI theme={null}
  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>'
  ```

  ```ts MKA1 SDK theme={null}
  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);
  ```

  ```ts fetch theme={null}
  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);
  ```

  ```bash bash theme={null}
  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"
      }
    }'
  ```
</CodeGroup>

Use [Retrieve an agent run](/api-reference/agent-runs/retrieve-an-agent-run) to poll status.
Use [Stream agent run events](/api-reference/agent-runs/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.

<CodeGroup>
  ```bash CLI theme={null}
  mka1 llm memory-stores list-entries \
    --memory-store-id mem_store_123 \
    --limit 20 \
    -H 'X-On-Behalf-Of: <end-user-id>'
  ```

  ```ts MKA1 SDK theme={null}
  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));
  ```

  ```ts fetch theme={null}
  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));
  ```

  ```bash bash theme={null}
  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>'
  ```
</CodeGroup>

See the [List memory entries API reference](/api-reference/memory-stores/list-memory-entries) and [Retrieve memory entry API reference](/api-reference/memory-stores/retrieve-memory-entry) 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](/api-reference/memory-stores/delete-memory-entry).