Skip to main content
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: 
# ~/.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: 
# ~/.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
ModeBehaviorWhen 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
isolatedEach 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: 
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: 
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.
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:
POST http://localhost:3111/agentmemory/mesh/sync
Both instances must have the same AGENTMEMORY_SECRET set for mesh sync to work.

​
Use Cases

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.
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.
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.