# How Macro AI Agents Access Team Memory and Use MCP Tools

> Discover how Macro AI agents access team memory via PostgreSQL and utilize MCP tools like ReadTeamMemory and WriteTeamMemory through a Streamable HTTP transport. Learn about Macro's architecture.

- Repository: [Macro/macro](https://github.com/macro-inc/macro)
- Tags: how-to-guide
- Published: 2026-08-18

---

**Macro's AI agents access shared team memory through a PostgreSQL-backed persistence layer exposed via the `team_memory` crate, while the MCP (Macro Communication Protocol) server provides eight core tools—including `ReadTeamMemory`, `WriteTeamMemory`, and `SendMessage`—that agents invoke through a Streamable HTTP transport.**

Macro is an open-source productivity platform (macro-inc/macro) that embeds AI agents directly into team workflows. These agents rely on **team memory** to maintain shared context across conversations and utilize a standardized set of **MCP tools** to interact with channels, tasks, and documents. Understanding how agents persist and retrieve team-wide data—and which specific tools are available—is essential for developers extending Macro's automation capabilities.

## The Team Memory Architecture

Macro's team memory system serves as a shared brain for AI agents, allowing them to recall previous interactions, project states, and user preferences across sessions.

### PostgreSQL Persistence Layer (`crates/team_memory`)

Team memory is stored in the primary **PostgreSQL** database (MacroDB) and managed through the `crates/team_memory` crate. This service exposes a CRUD interface with four primary operations: `get`, `set`, `list`, and `delete`. Each operation scopes data to a specific team ID, ensuring strict isolation between organizations.

The storage layer interacts with the `team_memory` table, where keys are namespaced per team. When an agent needs to recall information, it queries this table through the service layer rather than accessing the database directly, enforcing consistent access control and validation logic.

### ToolContext Injection in the AgentLoop

When an **AgentLoop** initializes in [`crates/agent/src/agent_loop.rs`](https://github.com/macro-inc/macro/blob/main/crates/agent/src/agent_loop.rs), it receives a configured **`ToolContext`** object. This context contains a pre-configured `team_memory` client that resolves the current user's team ID automatically.

The context is constructed at the service entry point—for example, in the Document Storage Service around lines 910–927 of its [`main.rs`](https://github.com/macro-inc/macro/blob/main/main.rs)—and passed into the agent runtime. Inside the loop, developers can invoke helper functions such as `agent::memory::read_team_memory`, which internally queries the `team_memory` table and injects the results directly into the LLM's prompt template.

```rust
// crates/agent/src/agent_loop.rs
fn run_agent(ctx: &ToolContext) -> Result<Response, Error> {
    // Access team memory through the injected context
    let project_context = ctx.team_memory.get("current_sprint_goals")?;
    
    // Inject into prompt for LLM reasoning
    let prompt = format!("Context: {}\nUser query: {}", project_context, user_input);
    Ok(llm.generate(&prompt))
}

```

## Available MCP Tools for Macro AI Agents

The **Macro Communication Protocol (MCP)** defines a standardized toolset that agents use to perform actions beyond text generation. These tools are hosted by the MCP server (`services/mcp_service`) and registered through the `ai_tools::all_tools()` function.

### Core Communication and Task Tools

The primary MCP tools enable agents to interact with the Macro workspace:

- **SendMessage**: Posts chat messages to channels or threads, allowing agents to communicate findings to human team members.
- **Search**: Executes full-text search across a team's document corpus, enabling retrieval-augmented generation (RAG) workflows.
- **CreateTask** and **UpdateTask**: Manage todo items, with `CreateTask` generating new work items and `UpdateTask` modifying status or metadata.
- **GetTeamMembers**: Retrieves the roster and role assignments for the current team, useful for routing messages or checking permissions.

These tools are implemented in [`services/mcp_service/src/tool_service.rs`](https://github.com/macro-inc/macro/blob/main/services/mcp_service/src/tool_service.rs) and exposed via HTTP endpoints that follow the Streamable MCP transport specification.

### Team Memory CRUD Operations

Four specialized tools provide direct access to the persistence layer:

- **ReadTeamMemory**: Retrieves a value by key from the team's memory store.
- **WriteTeamMemory**: Persists a key-value pair to the shared store, overwriting existing values if present.
- **ListTeamMemoryKeys**: Enumerates all keys stored for the current team, useful for discovery when the agent needs to know what context is available.
- **DeleteTeamMemory**: Removes specific entries (referenced in the architecture though not explicitly detailed in the tool list).

### Tool Registration and HTTP Transport

Tool registration occurs at service startup. The Document Storage Service (and similar entry points) calls `ai_tools::all_tools()` to enumerate available capabilities, which the MCP server then wraps as HTTP endpoints.

In [`services/mcp_service/src/main.rs`](https://github.com/macro-inc/macro/blob/main/services/mcp_service/src/main.rs), the server initializes the Streamable MCP transport layer that handles serialization, authentication, and request routing. When an agent decides to call a tool, it sends a structured request to this endpoint; the server validates the team ID, executes the underlying Rust function, and returns the result to the agent loop.

```rust
// services/mcp_service/src/tool_service.rs
pub fn all_tools() -> Vec<Box<dyn Tool>> {
    vec![
        Box::new(SendMessage),
        Box::new(Search),
        Box::new(CreateTask),
        Box::new(UpdateTask),
        Box::new(GetTeamMembers),
        Box::new(ReadTeamMemory),
        Box::new(WriteTeamMemory),
        Box::new(ListTeamMemoryKeys),
    ]
}

```

## Prompt Integration and Developer Documentation

The prompt engineering layer ensures agents know when to use memory tools. In [`crates/prompt/src/mcp_item_links.rs`](https://github.com/macro-inc/macro/blob/main/crates/prompt/src/mcp_item_links.rs), the system generates instruction blocks that tell the LLM how to reference MCP item-linking and memory operations. This bridges the gap between the agent's reasoning and the actual function calls.

For human-readable specifications, the `apps/docs/product/agents.mdx` file documents the complete agent capabilities and MCP toolset, serving as the authoritative reference for behavior contracts and expected parameters.

## Summary

- **Team memory** in Macro is stored in PostgreSQL and accessed via the `crates/team_memory` crate, providing isolated, persistent storage for each team.
- Agents receive memory access through a **`ToolContext`** injected at startup, typically instantiated in service entry points like the Document Storage Service.
- The **MCP server** (`services/mcp_service`) exposes eight core tools including `ReadTeamMemory`, `SendMessage`, and `CreateTask` through a Streamable HTTP transport.
- Tools are registered via `ai_tools::all_tools()` and implemented in [`tool_service.rs`](https://github.com/macro-inc/macro/blob/main/tool_service.rs), ensuring consistent availability across all Macro AI agents.
- Prompt templates in [`mcp_item_links.rs`](https://github.com/macro-inc/macro/blob/main/mcp_item_links.rs) guide the LLM in utilizing these tools effectively during conversation loops.

## Frequently Asked Questions

### What database does Macro use for team memory?

Macro uses **PostgreSQL** (referred to internally as MacroDB) to persist team memory. The `crates/team_memory` crate abstracts direct database access, exposing only `get`, `set`, `list`, and `delete` operations to the application layer. This ensures data isolation between teams and centralized transaction management.

### How do agents authenticate to read team memory?

Authentication happens during **ToolContext** construction. When a service like the Document Storage Service initializes an `AgentLoop` (around lines 910–927 of its [`main.rs`](https://github.com/macro-inc/macro/blob/main/main.rs)), it creates the context with a pre-configured team ID derived from the current user's session. The `team_memory` client in the context automatically applies this team ID to all queries, preventing cross-team data leakage without requiring manual authorization checks in the agent logic.

### Can custom MCP tools be added to Macro?

Yes. Custom tools can be added by implementing the Tool trait and registering the new tool in [`services/mcp_service/src/tool_service.rs`](https://github.com/macro-inc/macro/blob/main/services/mcp_service/src/tool_service.rs). After adding the implementation to the vector returned by `ai_tools::all_tools()`, the MCP server will automatically expose the new functionality through its HTTP endpoints. The `agents.mdx` documentation should be updated to reflect new capabilities for end-user transparency.

### Where is the MCP server configuration located?

The MCP server entry point resides in [`services/mcp_service/src/main.rs`](https://github.com/macro-inc/macro/blob/main/services/mcp_service/src/main.rs), where the Streamable transport layer is initialized. Tool-specific logic is defined in [`services/mcp_service/src/tool_service.rs`](https://github.com/macro-inc/macro/blob/main/services/mcp_service/src/tool_service.rs). Configuration for which tools are available to specific agents is typically handled at the service level (e.g., Document Storage Service) where `ai_tools::all_tools()` is invoked and filtered before context injection.