Skip to main content

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.

Use memory stores when an agent needs durable context that your application can update outside a conversation. Memory stores are useful for account notes, support playbooks, research briefs, or any content you want to reuse across many agent runs. For agents, memory stores are mounted through the shell tool environment. Each mount appears in the managed container under /mnt/memory/<label>. An entry path such as accounts/acme/preferences.md becomes a file path under that mount. 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>'
The response includes a memory store ID such as mem_store_.... 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>'
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>'
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>'
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>'
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.