Concepts

This page explains what Metateam does and how its pieces fit together. It is written for the person using the product, not for someone building on top of it. For mechanism details (hook payloads, ranking algorithms, compaction), see Internals.

The Mental Model

Metateam does four things:

  1. Remembers — every AI coding session is captured automatically. The system builds a searchable history of everything your agents have done.
  2. Learns — a Knowledge Base stores project conventions, architecture decisions, and gotchas. Agents receive this knowledge at the start of every session.
  3. Coordinates — multiple AI agents work on the same project simultaneously, communicating through messages and reports.
  4. Automates — multi-stage workflows defined as graphs can run agent pipelines with parallel branches, quality gates, and human review points.

These four capabilities reinforce each other. Sessions feed memory. Memory improves future sessions. The Knowledge Base shapes how agents work. Crews produce sessions that inform future crews. The feedback loop is the point.

The Dashboard

When you run metateam in a project directory, a terminal dashboard launches. This is the primary interface for human users.

The dashboard shows your active crew as tabs — one tab per agent. You interact with agents by typing in their tabs, and you manage the crew through keyboard shortcuts and slash commands. Press F12 to see the full shortcut list.

The dashboard is the control plane. Agents do the work. You set direction and review results.

Sessions

A session is one conversation between you (or an agent) and an AI coding client. Sessions are captured automatically when hooks are active — you do not need to save or upload anything manually.

What the system stores: the conversation in markdown format, along with metadata (working directory, git branch, timestamps, tags).

What you can do with sessions:

  • Browse and search from the web interface at metateam.ai/account/sessions.
  • Search from the terminal with metateam session search "query".
  • Load a full session with metateam session show <id>.

Sessions are the raw material for everything else. Memory is extracted from sessions. Context injection draws from session history. The system gets smarter because it has sessions to learn from.

Memory

Memory is the layer between raw sessions and useful knowledge. The system extracts facts from sessions automatically — decisions made, patterns discovered, problems solved — and stores them as searchable semantic memory.

When a new session starts, relevant memories are injected into the agent's context alongside KB entries. The agent does not start blank. It starts knowing what happened before.

You can also store facts manually with metateam memory remember "fact" and search them with metateam memory recall "query".

Knowledge Base

The Knowledge Base (KB) is a structured store of project knowledge: architecture decisions, coding conventions, deployment procedures, gotchas. Unlike sessions (which are captured automatically), KB entries are curated — written deliberately and organized by project and topic.

The hierarchy:

Project (e.g., "my-app")
└── Compartment (e.g., "gotchas", "architecture")
    └── Entry (e.g., "commit-style", "auth-design")

Entries can be marked as important. Important entries are automatically injected into every agent session for that project. This is the mechanism that turns documentation into active knowledge — write it once, mark it important, and every future agent session starts knowing it.

Keep important entries compact. Every important entry consumes agent context window. Over-marking entries degrades agent performance.

You can manage the KB from the web interface at metateam.ai/account/knowledge or ask agents to create and update entries during sessions.

Crew

A crew is a group of AI agents working on the same project. Each agent has a persona — a role that shapes how it approaches problems. One agent might optimize for performance, another writes tests, another reviews code for correctness.

The typical crew session:

  1. You run metateam. The dashboard launches with Data (your coordinator).
  2. You tell Data what you need. Data summons specialists and assigns tasks.
  3. Agents coordinate with each other through messages and mail-board reports.
  4. You observe from the dashboard, steer when needed, and review results.

Agents communicate through two channels:

  • Messages — short messages delivered directly to an agent's session. Good for quick coordination.
  • Mail-board reports — markdown files in .crew/mail-board/ for anything longer. Architecture proposals, reviews, implementation notes.

All crew activity is logged to .crew/history.md — a timestamped audit trail of summons, releases, and messages.

Attractor (Pipelines)

Attractor is a pipeline engine for multi-stage workflows. Pipelines are defined as graph files with nodes (tasks) and edges (dependencies). Each node can specify which persona runs it, what AI client to use, and what the task prompt is.

Pipelines support parallel branches, quality gates that retry on failure, and human review points that pause for your input.

You do not write pipeline files by hand. When you need a pipeline, describe the workflow to an agent and it generates the graph file. You run it with:

metateam attractor run --backend crew pipeline.dot

For the pipeline specification, see the Attractor reference in CLI Reference.

Project Detection

The system needs to know which project you are working in to inject the right KB entries and scope session search. Detection follows this precedence:

  1. Pin file — a .metateam.json file in the directory tree, created with metateam pin <project>. Overrides everything.
  2. Git remote — the repo's remote URL matched against registered projects.
  3. Directory path — the working directory matched against registered project paths.
  4. Single project — if only one project exists, it is used automatically.
  5. No match — sessions are still captured, but no KB entries are injected.

Next

  • The Daily Workflow — what a normal day looks like.
  • Crew Workflows — how multi-agent coordination works in practice.
  • Internals — mechanism details for session capture, context injection, and related systems.