@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
• Transfers context between sessions — local, CI, or team members
• 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 init

# or, if you're in a pnpm project:
pnpm dlx @first-to-fly/orchestrator-mcp 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 hooks in .claude/settings.local.json for session auto-inject and save reminders

4. Start a new Claude Code session — the orchestrator auto-connects and injects last session context

Manual Setup

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

.mcp.json

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

Environment Variables

How Context Transfers Between Sessions

1. Session ends — the agent saves a structured summary: what was accomplished, decisions made, blockers, files modified, next steps
2. Next session starts — the SessionStart hook auto-calls recall_context, injecting the last session summary and relevant entities into context
3. Agent picks up where the last left off — no re-explaining, regardless of whether it's the same developer, a different team member, or a CI agent

This works identically for local development, CI pipelines, and team members because Orchestrator is a remote service — not a file on your machine.

Available Tools (27)

Recall & Search

Store & Update

Sessions

Error Lifecycle

Work Queue

Recipes

Built-in Recipes

Maintenance

Approvals

Analytics

Entity Types

Protected types are never auto-pruned by prune_stale.

Requirement Structured Fields

Requirements support additional structured fields via store_entity:

Version History

Every entity update stores a version snapshot. Updates via both API (human) and MCP (agent) are tracked.

API endpoints (not MCP tools — agents don't need version history):

GET /projects/:slug/entities/:type/:id/versions
  → Returns version metadata: version number, editedBy, editedAt, source, changeReason

GET /projects/:slug/entities/:type/:id/versions/:version
  → Returns full content for a specific version (for diff comparison)

The update_entity MCP tool accepts a change_reason parameter to record why a change was made:

update_entity({ type: "requirement", id: "...", content: "...", change_reason: "Updated scope after stakeholder review" })

CLAUDE.md Protocol

The init command appends this protocol to your CLAUDE.md. It tells Claude Code when and how to use the orchestrator tools:

## Orchestrator Protocol

### Session Start
- Context is auto-injected via hook (last session + recalled memory)
- Call `recall_context` with your task description for relevant knowledge

### Progressive Retrieval
- `recall_context` and `search_memory` return summaries by default
- Use `get_entity(type, id)` only for entities you need full content from

### Error Resolution
- Call `check_error` before debugging from scratch — it may have a known fix

### Save Triggers
| Trigger | Entity Type |
|---------|------------|
| Architectural choice | `decision` |
| Reusable pattern found | `pattern` |
| Bug fixed | `error` |
| Task completed | `task` |
| Module created | `module` |
| Requirement clarified | `requirement` |
| Quick insight | `observation` |

### Relationships
Link related entities: `depends_on`, `supersedes`, `caused_by`, `implements`, `part_of`, `relates_to`

### Session Handoff
Before ending a session, call `save_session_summary` with:
- summary, tasksCompleted, tasksInProgress, blockers, filesModified, decisionsMade, nextSteps

### Maintenance
- `prune_stale` — remove unaccessed entities (dry run by default)
- `list_recent` — browse stored knowledge
- `search_memory` — find specific entities

Hooks

The init command sets up two hooks in .claude/settings.local.json:

• SessionStart: Auto-calls recall_context with the last session summary, so every new session inherits prior context without you doing anything
• Stop: Prompts Claude to call save_session_summary before the session ends if any meaningful work was done (files changed, bugs fixed, decisions made)

Works Everywhere

Links

• Web App
• GitHub
• Issues