> ## Documentation Index
> Fetch the complete documentation index at: https://agent-memory.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Share Memory Across Your Team with Team Memory

> Enable team-shared memory so multiple developers and agents share learned context, patterns, and decisions across a project — with per-agent scoping options.

Team Memory lets multiple agents and developers share the same memory pool for a project. When two agents work on the same codebase — or when you hand off from an AI agent to a colleague — they immediately have access to the same recalled context: architectural decisions, recurring bugs, environment quirks, and learned patterns. Team Memory is useful for onboarding new agents to existing codebases, running parallel feature workstreams, and coordinating handoffs between human and agent shifts.

## Enable Team Memory

Add these three variables to `~/.agentmemory/.env` on every machine that should share memory:

```env theme={null}
# ~/.agentmemory/.env
TEAM_ID=your-company
USER_ID=your-name
AGENT_ID=main-agent
```

* **`TEAM_ID`** — the shared namespace for your team or project. All instances with the same `TEAM_ID` share the same memory pool.
* **`USER_ID`** — identifies the human (or machine) running this instance. Used for audit trails and feed filtering.
* **`AGENT_ID`** — identifies the specific agent role (e.g. `architect`, `developer`, `reviewer`). Controls memory scoping (see below).

Restart Agent Memory after adding these variables.

## Memory Scoping

`AGENTMEMORY_AGENT_SCOPE` controls whether agents share a memory pool or each maintain their own private one within the team namespace:

```env theme={null}
# ~/.agentmemory/.env
AGENTMEMORY_AGENT_SCOPE=shared    # default: all agents read/write the same pool
# AGENTMEMORY_AGENT_SCOPE=isolated  # each agent gets its own private pool
```

| Mode               | Behavior                                                                                                                   | When to use                                                                 |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `shared` (default) | All agents on the team read from and write to the same memory pool. Every write is tagged with `AGENT_ID` for attribution. | Cross-agent context sharing, parallel feature development, onboarding       |
| `isolated`         | Each agent has a private memory pool. An `architect` agent cannot see memories from a `developer` agent, and vice versa.   | Strict role separation, security-sensitive contexts, independent evaluation |

In `shared` mode, you can still query memories by agent using `?agentId=<role>` on any REST endpoint, or pass `agentId` in the request body when saving memories.

## Sharing a Memory

To explicitly share a specific memory with your team, use the `memory_team_share` MCP tool from your agent, or call the REST API directly:

```json theme={null}
POST http://localhost:3111/agentmemory/team/share
Content-Type: application/json

{
  "itemId": "mem_abc123",
  "teamId": "your-company",
  "note": "Critical architecture decision — auth uses JWT with 24h expiry"
}
```

The memory becomes visible to all agents and users with the same `TEAM_ID`. The `note` field adds human-readable context to the shared item.

## Multi-Agent Coordination

When multiple agents work on the same project simultaneously, Agent Memory provides a set of coordination primitives to prevent duplicated work and enable messaging between agents.

### Work Items

Create and track actionable work items with dependency relationships:

* **`memory_action_create`** — create a new action with a title, description, priority, and optional dependencies on other actions.
* **`memory_action_update`** — update the status of an action (`pending`, `in_progress`, `done`, `blocked`).

### Exclusive Leases

Prevent two agents from picking up the same task simultaneously:

* **`memory_lease`** — acquire an exclusive lock on an action. If another agent already holds the lease, the request returns a conflict. Leases expire automatically after a configurable timeout.

### Agent-to-Agent Messaging

Send and receive messages between agents running in the same team:

* **`memory_signal_send`** — send a signal (message) to a named agent or broadcast to all agents in the team.
* **`memory_signal_read`** — read incoming signals with delivery receipts, so each signal is only processed once per agent.

### CI / Approval / Deploy Gates

Block an action until an external condition is met:

* **`memory_checkpoint`** — create a gate that an action cannot pass until the checkpoint resolves. Useful for CI results, human approvals, or deploy confirmations.

### Task Queue

Navigate the action graph to find the next unblocked task:

* **`memory_frontier`** — returns all actions whose dependencies have been completed, ranked by priority.
* **`memory_next`** — returns the single most important unblocked action for the current agent.

## Team Feed

Fetch recent shared memories from your team to get up to speed quickly:

```bash theme={null}
curl -X POST http://localhost:3111/agentmemory/team/feed \
  -H "Content-Type: application/json" \
  -d '{"teamId": "your-company", "limit": 20}'
```

The feed returns shared memories in reverse-chronological order, with attribution, notes, and links back to the source session.

<Note>
  Team Memory works across multiple machines as long as each instance is configured with the same `TEAM_ID`. Memories can be synchronized between instances using the mesh sync endpoint:

  ```bash theme={null}
  POST http://localhost:3111/agentmemory/mesh/sync
  ```

  Both instances must have the same `AGENTMEMORY_SECRET` set for mesh sync to work.
</Note>

## Use Cases

<AccordionGroup>
  <Accordion title="Onboarding a new agent to an existing codebase">
    When you spin up a fresh agent, configure it with your team's `TEAM_ID` and `USER_ID`. On its first session start, Agent Memory injects the team's shared context — architectural decisions, known bugs, environment setup patterns — directly into the agent's first prompt. The agent arrives already knowing what the team has learned.
  </Accordion>

  <Accordion title="Parallel feature development">
    Two agents work on different features simultaneously. With `AGENTMEMORY_AGENT_SCOPE=shared`, discoveries made by one agent (a flaky test, a performance pattern, an API quirk) are immediately visible to the other. Use `memory_action_create` + `memory_lease` to coordinate ownership of specific tasks without duplicating work.
  </Accordion>

  <Accordion title="Human-to-agent and agent-to-human handoffs">
    At the end of a working session, an agent uses the `/handoff` skill to write a structured summary of in-progress work into shared memory. When the next person (human or agent) picks up the work, they start with full context: what was tried, what worked, what's still open, and what to do next.
  </Accordion>
</AccordionGroup>