Add memory to Managed Deep Agents

Managed Deep Agents gives every deployment durable long-term memory in Context Hub. The agent reads and updates files under /memories/user/ across threads. With identity, memory is remounted per actor or tenant so callers cannot see each other’s private state.

Managed Deep Agents is in private beta, available on LangSmith Cloud in the US region only. Join the waitlist to request access.

What memory is (and is not)

Concept	Role	Survives redeploy?	Shared across sessions?
Instructions / skills	Deploy-owned harness behavior	Yes (synced from your project)	Yes (agent-wide)
Thread state	Conversation continuity (checkpointer)	Platform-managed	No (per thread)
Long-term memory	Preferences and durable notes in Context Hub `/memories/user`	Yes	According to identity scope
Store data	Structured data for tools (`StoreBackend`)	Yes	According to store namespace

Memory is not your system prompt. Edit instructions.md and skills/** in the project and redeploy. Deploy syncs those files but never overwrites existing memories/** in Context Hub.

Agent-visible layout

Agent path	Hub source	Access
`/instructions.md`	Hub `instructions.md`	Read-only
`/skills/**`	Hub `skills/**`	Read-only
`/memories/user/**`	One remounted Hub slice (for example `memories/<actor>`)	Read/write
`/memories/org/**`	Hub `org-memory/**` (if present)	Read-only

The agent never sees sibling actor or tenant trees. Isolation is the remount, not a multi-user listing under /memories.

Hot and cold memory

The runtime mounts a scoped Hub tree as /memories/user/ and injects hot memory every turn.

Tier	Path	When it loads
Hot	`/memories/user/AGENTS.md`	Always injected into the system prompt
Cold	Other files under `/memories/user/` (for example `archive/…`)	On demand via `read_file` / `write_file`

Keep hot memory small: preferences, short cursors, and pointers to cold files. Put digests, notes, and large artefacts in cold files and link them from hot memory when needed. Seed content for a new slice includes the Managed Deep Agents memory instructions marker. Do not delete that guidance block when editing hot memory.

How the agent updates memory

When the user shares a durable preference, the agent should update /memories/user/AGENTS.md with edit_file or write_file in the same turn—before claiming it will remember later. Tell the model that in instructions.md:

## Memory

You have durable memory under `/memories/user/`. Hot memory at
`/memories/user/AGENTS.md` is loaded every turn. Org facts (if present) are
read-only under `/memories/org/`.

When the user asks you to remember something durable:

1. Call `edit_file` (or `write_file` if creating) on `/memories/user/AGENTS.md`.
2. Confirm you stored it in persistent memory.

Never store secrets, API keys, OAuth tokens, or passwords in memory.

After a successful write, a new thread for the same caller should recall the fact from hot memory without calling tools. That is the product check for persistence across sessions.

Scope memory with identity

Without identity, every caller shares the same agent memory slice (memories/agent in Context Hub, remounted as /memories/user). With identity, scoping.memory chooses which Hub subdirectory is remounted:

`scoping.memory`	Hub path remounted as `/memories/user`
`actor` (single-tenant)	`memories/<actorId>`
`actor` (multi-tenant)	`memories/<tenantId>/<actorId>`
`tenant`	`memories/<tenantId>`
`agent`	`memories/agent`
`none`	No `/memories/user` mount (and no hot injection)

Isolation is hard: a run only sees its remounted tree. Sibling actor or tenant trees are unreachable. Presets such as private-assistant and internal-tool set memory: "actor". The service preset uses shared agent memory. For presets and ingress, see Identity.

from managed_deepagents import define_identity

identity = define_identity.preset("private-assistant")
# scoping.memory == "actor"

import { defineIdentity } from "managed-deepagents";

export const identity = defineIdentity.preset("private-assistant");
// scoping.memory === "actor"

On first use of an actor or tenant slice, the runtime seeds /memories/user/AGENTS.md from the agent seed (or a default template) so hot memory instructions are present on turn one.

Org memory (read-only)

Optional org-wide facts live under Context Hub org-memory/ and mount at /memories/org. Agents may read org memory; writes under /memories/org/** are denied. Humans or org tooling update that tree—not the agent.

Local development

mda build / mda dev maintain a local Context Hub mock at .mda/__contexthub__/:

Syncs instructions.md and skills/** from the project
Seeds memories/agent/AGENTS.md and org-memory/AGENTS.md when missing
Preserves existing memory files across rebuilds

Actor-scoped local runs remount memories/<actorId>/ as /memories/user the same way as deploy. After you change the SDK package used by the build, rebuild so .mda/build/__runtime__ picks up the new runtime (vendored at compile time).

Disable managed memory

Set disableMemory / disable_memory on the agent definition to skip hot injection and the /memories/user memory wiring. Identity scoping.memory: "none" also disables the mount.

from managed_deepagents import define_deep_agent

agent = define_deep_agent(
    model="openai:gpt-5.5",
    disable_memory=True,
)

import { defineDeepAgent } from "managed-deepagents";

export const agent = defineDeepAgent({
  model: "openai:gpt-5.5",
  disableMemory: true,
});

Deploy and Context Hub

On mda deploy, Managed Deep Agents syncs deploy-owned instructions.md and skills/** into the Context Hub agent repo and seeds agent memory when needed. Existing memories/** content is preserved. For the deploy lifecycle, see How Managed Deep Agents work and the CLI memory note.

Test and deploy

Test the project locally with mda dev, then deploy it with mda deploy. Open deployment traces in LangSmith to inspect model calls, tool calls, errors, and latency.

Next steps

Identity

Partition memory per actor or tenant with scoping.memory.

How it works

See how Context Hub, threads, and deploy sync fit together.

CLI reference

Look up project files, disableMemory, and deploy behavior.

Custom tools

Read runtime.identity when tools need the caller id.

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

​What memory is (and is not)

​Agent-visible layout

​Hot and cold memory

​How the agent updates memory

​Scope memory with identity

​Org memory (read-only)

​Local development

​Disable managed memory

​Deploy and Context Hub

​Test and deploy

​Next steps

Identity

How it works

CLI reference

Custom tools

What memory is (and is not)

Agent-visible layout

Hot and cold memory

How the agent updates memory

Scope memory with identity

Org memory (read-only)

Local development

Disable managed memory

Deploy and Context Hub

Test and deploy

Next steps