Tracing Docker Agent Memory From SQLite to Its Storage Layer

Docker Agent’s Memory Tool stores data in a SQLite database. The path to that database and the storage beneath it are separate concerns.

By default, the tool uses:

~/.cagent/memory/<config-name>/memory.db

That path alone does not establish whether the database is on the host, in a container filesystem, inside a bind mount, or on Linux tmpfs. The filesystem covering the path determines where the bytes live and whether they remain after the container stops.

This is a documentation-based storage map. It does not assume a particular Docker Agent deployment or container layout.

The Memory Tool defines a SQLite path

Docker describes the Memory Tool as persistent key-value storage backed by SQLite. Its data survives across agent sessions, allowing agents to recall stored information such as preferences, facts, project context, and past decisions (Docker Agent Memory Tool).

The documented default database path is:

~/.cagent/memory/<config-name>/memory.db

<config-name> is derived from the loaded configuration, typically its YAML filename, and falls back to default when no configuration name is available. When an agent is loaded from an OCI reference, reserved filesystem characters in this segment are sanitized (Docker Agent Memory Tool).

The documentation does not identify the underlying filesystem for every deployment. The default path therefore does not, by itself, establish that the database is:

• Directly on the Docker host
• In a container’s writable storage
• Covered by a bind mount
• Covered by a tmpfs mount
• Preserved when a container is stopped, removed, or recreated

The documented cross-session behavior describes the Memory Tool’s use of its database. It does not guarantee that the database survives every possible container lifecycle, because the storage beneath its path may have a shorter lifetime.

Database sharing and storage placement are separate

Agents declared in the same configuration share the default Memory Tool database. Docker documents an explicit path option that can be set per toolset to isolate databases (Docker Agent Memory Tool).

For example:

toolsets:
  - type: memory
    path: ./agent_memory.db

This option tells the Memory Tool which SQLite file to use. It does not create a Docker mount or select the underlying storage. Bind mounts and tmpfs mounts require separate Docker configuration (Docker bind mounts; Docker tmpfs mounts).

The same distinction applies to an absolute path such as:

/agent-data/memory.db

That value identifies the database from the application’s perspective. Whether /agent-data maps to a host directory, tmpfs, or some other filesystem depends on the deployment.

There are therefore two independent questions:

1. Database sharing: Which agents or toolsets use the same SQLite file?
2. Storage placement: What filesystem covers that file’s path?

A bind mount maps a container path to the host

A Docker bind mount maps a file or directory from the host into a container. Its source is the host path, while its destination is an absolute path inside the container (Docker bind mounts).

The general form is:

docker run --mount type=bind,src=<host-path>,dst=<container-path>

Consider this hypothetical layout:

Memory Tool path:       /agent-data/memory.db
Bind-mount source:      /srv/agent-memory
Bind-mount destination: /agent-data

The Memory Tool sees:

/agent-data/memory.db

Because /agent-data is the bind-mount destination, the corresponding file maps to:

/srv/agent-memory/memory.db

This mapping applies only if a writable bind mount is explicitly configured and covers the database path. Setting the Memory Tool’s path option does not configure that mount automatically.

Docker documents writable bind mounts as a way for files created in a container to persist on the host filesystem (Docker bind mounts). In this arrangement, the database can remain in the host source path after the container stops.

Host-backed persistence is not the same as a backup or a database-consistency guarantee. The supplied documentation also does not establish permission behavior for an unspecified Docker Agent deployment.

A tmpfs-backed database disappears on container stop

On Linux, Docker can mount tmpfs at a destination inside a container:

docker run --mount type=tmpfs,dst=<mount-path>

Unlike a bind mount, a Docker tmpfs mount has a container destination but no host source path (Docker tmpfs mounts).

Suppose the layout is:

Memory Tool path:  /agent-data/memory.db
tmpfs destination: /agent-data

The SQLite database then resides on the tmpfs mounted at /agent-data. Docker describes tmpfs as temporary storage in host memory. When the container stops, the mount is removed and files written there are not persisted (Docker tmpfs mounts).

The Memory Tool can use the database while that filesystem exists, but its cross-session storage cannot outlast the tmpfs mount. This arrangement would therefore not preserve the database across a container stop.

Two details are important:

• Linux may write tmpfs data to swap, so “host memory” does not mean the bytes can never reach a filesystem (Docker tmpfs mounts).
• tmpfs usage counts against the container’s memory-cgroup limit. Increasing tmpfs-size does not add memory beyond --memory or Compose’s mem_limit (Docker tmpfs mounts).

Docker documents this tmpfs functionality as available only when running Docker on Linux.

Storage map

Keep the boundary clear

To locate a Memory Tool database, begin with its configured path and then determine which filesystem covers that path.

For a bind mount, trace the container destination to its host source. For tmpfs, there is no host source: the data is temporary, counts against the container’s memory limit, and disappears when the container stops. If the mount arrangement is unknown, the database path alone is insufficient to determine physical location or lifecycle.

The cited pages do not establish a universal Docker Agent container layout or say that Docker Agent automatically configures either mount type. They also do not provide deployment-specific guarantees for backup, recovery, permissions, performance, or SQLite consistency.

Sources and further reading

• https://docs.docker.com/ai/docker-agent/tools/memory/
• https://docs.docker.com/engine/storage/bind-mounts/
• https://docs.docker.com/engine/storage/tmpfs/