Memory structure

Agent memory in relay is split into two layers: session memory and project memory.

File structure

my-project/
└── .relay/
    ├── memory/                  # persistent memory across sessions (recommended to git-commit)
    │   ├── project.md           # architecture, domain, and tech stack summary
    │   └── agents/
    │       ├── pm.md            # PM personal memory
    │       ├── fe.md            # FE: component structure, conventions
    │       ├── be.md            # BE: API patterns, DB schema
    │       ├── da.md            # DA: event / metrics taxonomy
    │       ├── designer.md      # Designer: UI patterns, design system
    │       ├── qa.md            # QA: recurring bug patterns, fragile areas
    │       └── deployer.md      # Deployer: deployment history, cautions
    └── sessions/                # per-session summaries (gitignored; auto-generated)
        ├── 2026-03-13-001/
        │   └── summary.md
        └── ...

Session memory (in-memory)

Within-session data lives in the MCP server process memory:

• Messages
• Tasks
• Artifacts
• Reviews
• WebSocket events

This data is ephemeral — it exists for the duration of the server process and is not written to disk.

When a session ends, save_session_summary writes a human-readable summary to .relay/sessions/{session_id}/summary.md. The sessions directory is gitignored — it is local-only.

Project memory (Markdown files)

Memory that persists across sessions is stored as Markdown files in .relay/memory/.

project.md

The project-wide summary written at the end of the first /relay:relay session:

• Domain and key features
• Architecture overview
• Team conventions

agents/{agentId}.md

Each agent’s personal memory:

• Role-specific important code patterns
• Conventions discovered in previous sessions
• Cautions for specific areas

Memory MCP tools

Reading

// Read an agent's personal memory
read_memory({ agent_id: "fe" });
// → returns .relay/memory/agents/fe.md

// Read project memory (omit agent_id)
read_memory({});
// → returns project.md

Writing (section overwrite)

// Write to an agent's personal memory
write_memory({
  agent_id: "fe",
  key: "component-patterns",
  content: "Button components always use shadcn/ui as the base...",
});
// replaces the ## component-patterns section in .relay/memory/agents/fe.md

// Write to project memory (omit agent_id)
write_memory({
  key: "architecture",
  content: "Monorepo with packages/server, packages/dashboard, packages/shared",
});
// replaces the ## architecture section in .relay/memory/project.md

Appending (cumulative)

// Append to an agent's personal memory (agent_id is required)
append_memory({
  agent_id: "qa",
  content: "2026-03-13: found missing empty-email case in login flow",
});

Session lifecycle

On session start

Automatically injected into each agent’s system prompt:

1. project.md (project memory)
2. agents/{agentId}.md (personal memory)

On session end

1. Each agent saves new discoveries via write_memory or append_memory
2. save_session_summary archives the session

Team sharing

It is recommended to commit .relay/memory/ files to git so the whole team shares them:

git add .relay/memory/
git commit -m "chore: update relay memory"

This lets new team members and new Claude Code sessions immediately benefit from the context of previous sessions.

RELAY_DIR environment variable

The default memory path is {cwd}/.relay, but it can be changed via the RELAY_DIR environment variable:

RELAY_DIR=/path/to/shared/.relay bun run start