Memory bundles

A Memory bundle is a reusable, provider-agnostic capability pack — system prompt (“Soul”), instructions, context files, MCP servers, skills. Provider and model belong to the agent, chosen separately at launch, not to the bundle. Selectable at launch from the Launch Agent modal.

What goes in a Memory

Bundles are provider-agnostic — provider and model belong to the agent, chosen at launch, not to the bundle. Today’s New/Edit Bundle form exposes Name, Description, and Instructions; Context files, MCP servers, and Skills are persisted in the schema (round-trip cleanly) but aren’t yet editable through the form:

Field	Purpose	Editable in the UI today?
`instructions`	System prompt / Soul. Long-form text describing the agent’s personality, priorities, and behavior. Prepended to the context at launch.	Yes
`context_files`	Array of `{path, content}` entries — files (typically project-scoped, like `AGENTS.md` or `CLAUDE.md`) loaded into context on launch.	Not yet — persisted as JSON
`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.	Not yet — persisted as JSON
`skills`	Array of Skill primitive IDs (a real reference, unlike `mcp_servers`/`context_files`) — see Skills in the Armory.	Not yet — persisted as JSON
`provider` / `model`	Vestigial DB columns from before bundles went provider-agnostic. Not exposed in the form; not consumed at launch.	No

A “vanilla CLI session” is the singleton is_blank Memory bundle at the top of the Launch modal — not a bundle with fields merely left empty.

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.

Durability across channels and builds

Native memory is durably mirrored, not just live-filesystem state. db_agent_native_memory (a global-scoped store, alongside db_bundles/db_accounts) keys a copy of every memory file’s content by (agent_id, filename), where agent_id is the same stable AgentDefinition.id the Brain tab’s handlers already resolve to — not the live filesystem path, which is channel-relative by construction: it depends on the per-channel working_directory and the identity’s CLAUDE_CONFIG_DIR, so the same logical agent, opened from two different channels/builds, computes two different on-disk memory paths.

Every memory.list / memory.read call (and the agent-callable MemoryList/MemoryRead MCP tools) writes through into this mirror, then merges the live-filesystem file set with the mirror’s file set for its response: a file present in both is served from the live FS (it’s the freshest — Claude may have written it moments ago); a file present only in the mirror — written from a different channel, or the live folder was wiped — is served from the mirror transparently, with no distinguishing “not found on this channel” state. memory.write/MemoryWrite upserts the mirror the same way on save.

Net effect: once a memory file has been viewed (listed or read) from any channel/build, the same content stays visible from every other channel/build for that same agent identity — reopening an agent’s Brain tab after a version upgrade, or from a different task package build, still shows everything Claude has written for it, with the user never aware of the underlying CLAUDE_CONFIG_DIR/cwd-hash path mechanics. The one known gap: a fact Claude writes autonomously in a session that’s never reopened in the Brain tab before that channel’s filesystem is wiped is not captured (no filesystem watcher exists yet). See docs/specs/SPEC_NATIVE_MEMORY_DURABLE_SYNC_2026_08_07.md in the main repo for the full design.

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.