How Macro AI Agents Access Team Memory and Use MCP Tools

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

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

// 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, 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, ensuring consistent availability across all Macro AI agents.
• Prompt templates in 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), 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. 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, where the Streamable transport layer is initialized. Tool-specific logic is defined in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}