@first-to-fly/orchestrator-mcp

Persistent, structured memory for Claude Code via MCP.

Claude Code has two built-in memory mechanisms — CLAUDE.md (static instructions) and auto memory (a 200-line markdown notepad). Both are local files tied to one machine with no search, no structure, and no way to share context between developers or CI agents.

Orchestrator adds a third layer: a database-backed memory system with typed entities, relationships, relevance-scored recall, and lifecycle management — accessible from any environment via API key.

What it does

• Recalls past decisions so you don't re-explain architecture every session
• Remembers error fixes so the same bug doesn't get debugged twice
• Builds project context — agents understand what was built and why
• Stores patterns with examples so agents follow your conventions
• Manages a work queue so webhook events become tasks agents pick up
• Tracks costs per session so you know what you're spending

Quick Start

1. Sign up at orchestrator.firsttofly.com and create a project
2. Generate an API key from the project's Setup page
3. Run the init command in your project directory:

npx @first-to-fly/orchestrator-mcp@latest init

This will:

• Prompt for your API URL, key, and project slug
• Validate the API key against the server
• Create .mcp.json with the MCP server config
• Append the orchestrator protocol to CLAUDE.md
• Set up the PreCompact hook in .claude/settings.local.json
• Seed built-in recipes

4. Start a new Claude Code session — the orchestrator auto-connects

Two MCP Packages

The orchestrator is split into two MCP servers to keep the agent's tool list focused:

| Package | Tools | Purpose | | -------------------------------------- | ----- | --------------------------------------------- | | @first-to-fly/orchestrator-mcp | 12 | Daily agent use — recall, store, specs, queue | | @first-to-fly/orchestrator-mcp-admin | 11 | Management — scaffold, bulk ops, prune, audit |

Most projects only need the agent MCP. Add the admin MCP when you need to scaffold a project, bulk-seed knowledge, manage the work queue, or audit entity history.

Agent Tools (12)

Recall

| Tool | What it does | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | recall | Retrieve relevant context for a task. Hybrid scoring with tiered rendering (mode: "context") or keyword search (mode: "search"). | | get_entity | Fetch full entity content, metadata, and attachments by type and ID. | | check_error | Check if a similar error was seen before. May return a known fix. |

Store

| Tool | What it does | | -------------------- | ------------------------------------------------------------------------------------------------------------------ | | store_entity | Create or update a knowledge entity (single or array via entities). Deduplicates by type+name, or updates by ID. | | store_relationship | Link two entities with a typed relationship (single or array via relationships). |

Sessions

| Tool | What it does | | ---------------------- | ----------------------------------------------- | | save_session_summary | Save a structured handoff for the next session. |

Specs

| Tool | What it does | | -------------------- | ------------------------------------------------------------------------ | | compose_spec | Compose a spec document from a root requirement (omit ID to list roots). | | analyze_spec | Review spec quality — conflicts, ambiguities, gaps, suggestions. | | save_smoothed_spec | Upload a smoothed specification document. |

Recipes

| Tool | What it does | | -------- | ----------------------------------------------------------- | | recipe | Get a recipe by name, or list all recipes if no name given. |

Queue

| Tool | What it does | | ----------------- | -------------------------------------------------------------- | | claim_next_task | Claim the highest-priority unclaimed work item from the queue. | | resolve_task | Mark a work item as completed or failed. |

Hook: PreCompact

The init command sets up a single hook in .claude/settings.local.json:

• PreCompact: Before Claude Code compresses context, this hook saves a session summary to the orchestrator so context survives compression.

Entity Types

| Type | Purpose | Stale after | TTL | Protected | | ------------- | ------------------------------------------------------------- | ----------- | --------- | --------- | | module | Code areas and architecture | 180 days | Permanent | No | | decision | Architectural choices with rationale, alternatives, tradeoffs | 365 days | Permanent | Yes | | pattern | Reusable approaches with example files and anti-patterns | 365 days | Permanent | Yes | | requirement | Specs and requirements with acceptance criteria | 365 days | Permanent | Yes | | error | Bug + fix pairs with stack traces and root cause | 60 days | 90 days | No | | task | Completed work with files modified and outcome | 30 days | 90 days | No | | observation | Quick insights and notes | 60 days | 90 days | No | | session | Structured handoff summaries between sessions | 180 days | 180 days | Yes |

Protected types are never auto-pruned by prune_stale.

CLAUDE.md Protocol

The init command appends this protocol to your CLAUDE.md:

## Orchestrator Protocol

### Retrieve Knowledge First

- `recall` — start here: assembles relevant entities with tiered rendering (mode: context) or keyword search (mode: search)
- `get_entity` for full content of a specific entity
- `check_error` before debugging — a known fix may exist

### Living Specifications

- `compose_spec` — read composed specs from requirement entities (omit ID to list roots)
- `analyze_spec` — review spec quality before smoothing
- `save_smoothed_spec` — cache a polished version for future sessions

### Store Significant Knowledge

Store what compounds across sessions — not everything, just what matters:

- **Decisions**: architectural choices with rationale (the WHY)
- **Patterns**: reusable approaches worth repeating, with anti-patterns
- **Errors**: bugs with root cause + fix, so the same mistake isn't debugged twice
- **Requirements**: specs that define what to build (link via `part_of` to a root)

`store_entity` handles both create (by type+name) and update (by id).

### Relationships & Sessions

- Link entities: `depends_on`, `supersedes`, `caused_by`, `implements`, `part_of`, `relates_to`
- `save_session_summary` when ending with meaningful work worth preserving

Built-in Recipes

| Recipe | Triggers | What it does | | --------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------- | | debug-error | debug, error, fix, bug | Guided error debugging workflow: check → investigate → store → resolve | | new-module | new module, create module, scaffold | Scaffold a new backend module following conventions | | session-handoff | end session, wrap up, done for today | Template for saving a complete session summary | | knowledge-capture | learned, discovery, insight, remember | Decision tree for choosing the right entity type | | bootstrap-knowledge | bootstrap, scaffold, index project | Comprehensive codebase analysis and knowledge indexing | | investigate-area | how does, understand, explore | Systematic approach to understanding a code area | | capture-spec | spec, requirement, feature, user story | Capture requirements as versioned, structured entities | | implement-from-spec | implement spec, implement requirement, build feature | Implement a feature by reviewing its stored requirements first |

Manual Setup

If you prefer to configure manually, create these files in your project root.

.mcp.json

{
  "mcpServers": {
    "orchestrator": {
      "command": "npx",
      "args": ["-y", "@first-to-fly/orchestrator-mcp@latest"],
      "env": {
        "ORCHESTRATOR_API_URL": "https://orchestrator.firsttofly.com/api/v1",
        "ORCHESTRATOR_API_KEY": "ftfo_your_key_here",
        "ORCHESTRATOR_PROJECT": "your-project-slug"
      }
    }
  }
}

Environment Variables

| Variable | Description | Required | | ---------------------- | ---------------------------------------------------------------- | -------- | | ORCHESTRATOR_API_URL | API endpoint (e.g. https://orchestrator.firsttofly.com/api/v1) | Yes | | ORCHESTRATOR_API_KEY | Project API key (starts with ftfo_) | Yes | | ORCHESTRATOR_PROJECT | Project slug | Yes |

Works Everywhere

| Environment | How it connects | What it gets | | --------------- | ---------------------------------- | ------------------------------------------------------------------------- | | Local developer | MCP server in Claude Code settings | Full memory — recall, store, queue, recipes | | CI agent | Same MCP config with API key | Same memory — PR review agents recall project patterns and past decisions | | Team member | Shared project, own API key | Shared knowledge — one developer stores a decision, another recalls it |

Links

• Web App
• GitHub
• Issues