> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-5e9cc07a-preview-cbdocs-1784316992-3f2f380.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Add memory to Managed Deep Agents

> Persist preferences and knowledge across threads with Context Hub memory in Managed Deep Agents.

Managed Deep Agents gives every deployment durable long-term memory in [Context Hub](/langsmith/use-the-context-hub). The agent reads and updates files under `/memories/user/` across threads. With [identity](/langsmith/managed-deep-agents-identity), memory is remounted per actor or tenant so callers cannot see each other's private state.

<Note>
  Managed Deep Agents is in **private [beta](/langsmith/release-stages)**, available on [LangSmith Cloud](/langsmith/cloud) in the US region only. [Join the waitlist](https://www.langchain.com/langsmith-managed-deep-agents-waitlist) to request access.
</Note>

## 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](#scope-memory-with-identity) |
| **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`:

```md theme={null}
## 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](/langsmith/managed-deep-agents-identity).

<CodeGroup>
  ```python identity.py theme={null}
  from managed_deepagents import define_identity

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

  ```ts identity.ts theme={null}
  import { defineIdentity } from "managed-deepagents";

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

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.

<CodeGroup>
  ```python agent.py theme={null}
  from managed_deepagents import define_deep_agent

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

  ```ts agent.ts theme={null}
  import { defineDeepAgent } from "managed-deepagents";

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

## 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](/langsmith/managed-deep-agents-how-it-works#context-hub) and the [CLI memory note](/langsmith/managed-deep-agents-cli#memory).

## Test and deploy

Test the project locally with [`mda dev`](/langsmith/managed-deep-agents-cli#develop-locally), then deploy it with [`mda deploy`](/langsmith/managed-deep-agents-deploy). Open deployment traces in LangSmith to inspect model calls, tool calls, errors, and latency.

## Next steps

<CardGroup cols={2}>
  <Card title="Identity" icon="fingerprint" href="/langsmith/managed-deep-agents-identity">
    Partition memory per actor or tenant with `scoping.memory`.
  </Card>

  <Card title="How it works" icon="settings" href="/langsmith/managed-deep-agents-how-it-works">
    See how Context Hub, threads, and deploy sync fit together.
  </Card>

  <Card title="CLI reference" icon="terminal" href="/langsmith/managed-deep-agents-cli">
    Look up project files, `disableMemory`, and deploy behavior.
  </Card>

  <Card title="Custom tools" icon="tool" href="/langsmith/managed-deep-agents-tools">
    Read `runtime.identity` when tools need the caller id.
  </Card>
</CardGroup>

***

<div className="source-links">
  <Callout icon="terminal-2">
    [Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
  </Callout>

  <Callout icon="edit">
    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/langsmith/managed-deep-agents-memory.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>
</div>