When Shared Memory Becomes a Coordination Plane

agentmemory changes character when more than one agent can reach the same runtime. The key question is no longer only whether a memory is relevant, but who may recall it, who may deliberately share it, and who may claim the work it describes. This chapter separates those boundaries and examines the controls around them—agent scope, team sharing, leases, signals, checkpoints, audit, deletion, and network exposure—so a shared memory arrangement can be designed deliberately rather than assumed safe.

Visibility is not ownership

Imagine an architect, an implementer, and a researcher working through one memory service. They may all benefit from knowing that a project chose one database library, but they may not all be allowed to see every private observation. They may also need to know which engineer owns the current migration task. A single “shared memory” setting cannot answer all three questions.

Agentmemory addresses the first question with AGENT_ID. When an agent identity is available, it can be carried into session records, raw observations, compressed observations, and explicit memories. The tag says who produced a record. It does not, by itself, make the record private. In the default shared scope, the tag remains useful provenance while recall can still see records from other agents. This supports cross-role context: one agent can learn what another discovered while retaining the identity of the contributor.

Isolated scope changes the read rule. Search, smart search, and generated context filter records by the active agent identity. A role working in isolation should not accidentally retrieve another role's observations just because both roles use the same server. If isolation is enabled but no identity can be resolved from the environment or request, the recall path fails closed instead of treating the missing identity as permission to read everything. A caller can request a wildcard explicitly when a cross-agent view is genuinely intended.

That fail-closed behavior is more than a defensive coding detail. Consider a worker process that starts with an environment variable naming the architect, then handles a request routed from the implementer. If the request does not carry the implementer's identity, silently using the process identity could return the architect's context to the implementer; if no identity is available at all, an unfiltered read would create another kind of leak. Refusing the request is inconvenient, but it makes the missing identity visible at the point where access would otherwise become ambiguous.

The boundary is not perfect just because the filter exists. A record with no agent tag is not equivalent to a record tagged for the current agent. Legacy or unscoped data may be treated as unscoped for compatibility. Shared scope, isolated scope, and an explicit wildcard are different operating choices, and each has a different privacy consequence. Operators must decide whether cross-role learning or strict separation is more important for each runtime.

Team sharing is a separate action. With TEAM_ID and USER_ID, an agent can deliberately share a memory, observation, or pattern into a team namespace. A team feed can return shared items, and a team profile can summarize concepts, files, and patterns contributed by members. The deliberate share step matters because a private role-scoped observation should not become a team artifact merely because several agents happen to use the same server.

Peer mesh is separate again. Sharing into a team namespace and synchronizing with another agentmemory instance are not the same as filtering recall within one process. A mesh can move state between runtimes; agent scope decides which tagged rows a caller may read; team sharing creates a deliberate collaborative record. The project roadmap also identifies a broader cross-agent shared namespace as future work, so a collection of installations should not be assumed to share one corpus automatically.

The same separation applies to work ownership.