@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:

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

Store

Sessions

Specs

Recipes

Queue

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

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

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

Works Everywhere

Links

• Web App
• GitHub
• Issues