Memory bundles

A Memory bundle is a reusable agent definition — everything that makes the agent behave like itself. Provider, model, system prompt (“Soul”), instructions, context files, MCP servers, skills. Selectable at launch from the Launch Agent modal.

What goes in a Memory

Field	Purpose
`provider`	One of the seven supported providers — `claude`, `codex`, `gemini`, `openclaw`, `kimi`, `copilot`, `pi`. Determines the CLI binary, controller type, and stream parser.
`model`	Model identifier passed to the provider (e.g. `claude-sonnet-4-6`).
`instructions`	System prompt / Soul. Long-form text describing the agent’s personality, priorities, and behavior. Prepended to the context at launch.
`context_files`	Array of `{path, content}` entries — files (typically project-scoped, like `AGENTS.md` or `CLAUDE.md`) loaded into context on launch.
`mcp_servers`	Per-bundle MCP server configuration, stored as an inline JSON copy — not a reference to the MCP Server primitive catalog. Editing a catalog server after the fact doesn’t change what’s already baked into a bundle.
`skills`	Array of Skill primitive IDs (a real reference, unlike `mcp_servers`/`context_files`) — see Skills in the Armory.

A “vanilla CLI session” is a Memory bundle with all fields blank except provider. The singleton blank Memory at the top of the Launch modal selects exactly this case.

Session zones and default-continue

A Memory bundle keeps a sequence of session zones — one per agent-anchored conversation thread. When you re-launch the same Memory bundle, the agent defaults to continuing the most recent session rather than starting fresh: previous turns load into the new pane, the agent’s context carries over, and you pick up mid-thread.

If you want a brand-new conversation instead, the Launch modal’s Recent sessions tab lets you pick a specific older session to re-attach to (or click + to start a fresh zone). The default is “continue most recent” because that matches the workflow people actually have — close a pane, reopen, keep going.

Session zones are anchored to the agent’s identity (agent_id), not the pane that hosts the conversation. Moving an agent to a new pane preserves its zones; deleting the pane preserves them too. The Swarm pane’s history tab is the canonical browser for zones across all your agents.

How Memory bundles are reached

Bundles are app-wide only today — there is no per-agent “Bundle” tab in the current agent-pane setup modal.

App-wide manager:

Click the hamburger (≡) at the top of the tab bar.
Choose Armory.
Switch to the Bundles tab.

The view registration (view: "memory") and MemoryPaneViewModel exist so pane.open RPC and right-click menus can reach a bundle-scoped view, but the primary path today is the Armory’s Bundles tab.

Native memory (“Brain”)

Distinct from a Bundle, native memory is a set of free-form .md files an already-running agent reads and writes about itself — notes, running context, anything it wants to persist across turns, independent of any bundle definition.

Per-agent: open an Agent pane → Agent setup icon (id-card) → Memory tab.
App-wide: hamburger menu (≡) → Armory → Brain tab, browsing every agent’s notes in one place.

Both surfaces, and an agent acting on itself, go through the same primitive:

Surface	Commands
App API	`memory.list`, `memory.read`, `memory.write`
MCP tools (agent-callable)	`MemoryList`, `MemoryRead`, `MemoryWrite`

See Agent App API for the full parameter reference.

Launch flow

The Launch Agent modal exposes a single Memory dropdown alongside the Identity dropdown:

┌────────────────────────────────────────────────┐
│ New Agent Instance                              │
│  Name:         [my-instance______]              │
│  Runtime:      [local | container]              │
│                                                 │
│  Identity:     [▼ — Blank (no creds) —    ]     │
│  Memory:       [▼ — Blank (vanilla CLI) — ]     │
│                                                 │
│  [Cancel]              [Launch]                 │
└────────────────────────────────────────────────┘

If Memory is blank, the agent launches with the provider’s defaults — no instructions, no context files, no per-bundle MCP overrides. A real Memory selection composes the provider’s launch args with the bundle’s settings.

Persistence

Memory bundles live in db_memory_bundles in the sidecar’s objects.db:

id              TEXT PRIMARY KEY
name            TEXT NOT NULL UNIQUE
description     TEXT
is_blank        INTEGER NOT NULL DEFAULT 0
provider        TEXT
model           TEXT
instructions    TEXT
context_files   TEXT  -- JSON
mcp_servers     TEXT  -- JSON
skills          TEXT  -- JSON
created_at      TEXT NOT NULL
updated_at      TEXT NOT NULL

db_memory_bundles is part of objects.db’s flat schema (run_object_schema). Memory replaced the earlier “Forge” concept; the agent-definition catalog (“Forge agents”) now lives separately in db_agent_definitions.

Memory and per-instance overrides

A Memory bundle is the definition — reusable across many agent instances, edited from the Armory’s Bundles tab.

When you launch an agent, AgentMux composes the bundle’s settings with whatever overrides the running pane has accumulated, then spawns the provider’s CLI with the resulting launchArgs and env. Two agents using the same Memory bundle but different overrides land on different actual configs at launch.