Concepts

How Fellowship orchestrates AI agents with memory, specs, and code review.

How It Works

When you run a task, Fellowship orchestrates a full pipeline:

The Memory System

Fellowship's memory is a local SQLite graph — no vector database, no embeddings, no external infra. It runs on your machine, commits to your repo, and grows with every run.

The graph has two layers:

Layer 1 — Memory Graph (MCP)

The core. A structured knowledge graph exposed to agents via an MCP server. Every run, agents must search it before writing code. Every decision, gotcha, or lesson is recorded as a node.

Mandatory Protocol

Agents follow this protocol on every run — it's enforced in the agent prompt, not just suggested:

1. MANDATORY FIRST STEP: graph_search with task keywords
2. Before writing any code: minimum 2 graph_query calls
3. During implementation: record learnings/gotchas/decisions when friction occurs
4. Post-run: graph is enriched for the next agent

Layer 2 — Markdown files (human-readable)

Alongside the graph, Fellowship maintains plain Markdown files you can read, edit, and commit:

Spec-First Workflow

Every task gets a detailed spec before any code is written. The spec engine combines your task with graph context:

• Memory Graph results — graph_search finds relevant learnings, gotchas, decisions
• Agent profile — role-specific guidelines and conventions
• Architecture — from graph or architecture.md as fallback

This means the agent starts with a complete picture — not just your one-liner task description. You can preview any spec before running it:

# Preview the spec without executing
fellowship run "add WebSocket support" --dry-run

# Or generate just the spec file
fellowship spec "add WebSocket support"

Agents & Roles

Fellowship creates a team of specialized agents, each with a role, profile, and memory. Agents are defined in .fellowship/team.yaml and have individual profile files in .fellowship/profiles/.

A typical team might include:

• Carlos (Backend) — handles API endpoints, business logic, database queries
• Atlas (Database) — schema design, migrations, query optimization
• Merlín (Coordinator) — project-level decisions and planning
• Sentinel (Reviewer) — code review on every run

Fellowship automatically selects the right agent for each task based on the agent’s role and the task description. You can also add new agents with fellowship hire.

Writer-Reviewer Pattern

Fellowship uses a writer-reviewer pattern for every run. The coding agent (writer) implements the task, then Sentinel (reviewer) checks the code against the spec.

This creates a feedback loop:

1. Writer implements the code based on the spec
2. Sentinel reviews against acceptance criteria, catches bugs and edge cases
3. If issues found, the writer gets feedback and fixes them
4. Cycle repeats up to maxCycles (default: 2)
5. After passing review, changes go to human review (if --review flag used)

Sentinel — The Built-in Reviewer

Every project gets Sentinel, a dedicated AI code reviewer. Unlike using another coding agent as reviewer, Sentinel has a specialized profile focused on:

• Verifying acceptance criteria from the spec
• Catching bugs and missing edge cases
• Checking architecture compliance
• Not nitpicking style or suggesting rewrites

Sentinel reviews every run automatically. Configure via review: in config.yaml.

Background Runs

Background runs let the agent work while you keep coding. Your terminal stays free — no waiting around.

# Start a background run
fellowship run "add authentication" --bg

# Check on it any time
fellowship status
fellowship log --follow

# Review when notified
fellowship review

The agent works in an isolated git worktree, so there’s zero risk of conflicts with your current work. When it finishes, you get a notification.

Notifications

Fellowship notifies you when runs complete — zero config required.

Built-in (automatic)

Plus: terminal flash — colored bar on completion (green / red / yellow / blue).

Additional Providers

• Telegram — set bot token + chat ID in config or env vars
• Slack — set webhook URL in FELLOWSHIP_SLACK_WEBHOOK env var
• Custom — any shell command with env vars

Environment Variables in Hooks

Memory Graph (MCP)

The Memory Graph is a local SQLite-backed knowledge graph that persists structured knowledge across every run. It's exposed to agents via an MCP (Model Context Protocol) server.

Node Types

MCP Tools Exposed

Mandatory First Step

Every run begins with a graph_search before any code is written. This ensures the agent consults accumulated project knowledge — gotchas, past decisions, known patterns — before starting implementation.

Organic Registration

Knowledge is only recorded when there's real friction or a meaningful insight. The graph grows gradually and intentionally, not by noise — keeping retrieval signal high.

Graph Versioning

The Memory Graph is portable. Export it to a .jsonl.gz file, commit it to your repo, and anyone who clones the project can restore full knowledge with fellowship import.

What to commit

# Export and commit the graph
fellowship export
git add .fellowship/graph.jsonl.gz
git commit -m "chore: update knowledge graph snapshot"

# New team member restores full knowledge
git clone <repo>
fellowship import

Smart Agent Selection

When you run a task, Fellowship automatically picks the most appropriate agent from your team. The selection uses a two-phase approach:

1. Keyword matching — each agent's scope in team.yaml is scored against the task description
2. LLM fallback — if no agent scores above HIGH_CONFIDENCE_THRESHOLD = 0.4, an LLM call disambiguates

You can bypass the selector with the --agent <id> flag:

# Let Fellowship pick the agent
fellowship run "add login form"

# Force a specific agent
fellowship run "add login form" --agent carlos

Improving Selection via team.yaml

A well-defined scope field in team.yaml is the most effective way to improve automatic selection. Include specific technologies, file paths, and task verbs that belong to each agent:

agents:
  - id: luna
    role: Frontend engineer
    scope: React components, CSS, UI, forms, pages, routing, Tailwind
  - id: carlos
    role: Backend engineer
    scope: API endpoints, database queries, auth, middleware, services

fellowship fix

fellowship fix is a specialized command for bug resolution. It runs a three-step pipeline:

1. Diagnose — analyzes the bug description against the codebase and memory graph
2. Generate fix spec — produces a targeted spec scoped to the specific defect
3. Run — executes the fix using the most appropriate agent

fellowship fix "payment webhook returns 500 when amount is zero"

Unlike fellowship run, the fix command treats the input as a bug description rather than a feature request. The spec engine focuses on root-cause analysis and minimal targeted changes.

fellowship memory — Interactive TUI

fellowship memory (alias: fellowship mem) opens an interactive terminal UI for browsing everything Fellowship knows about your project.

fellowship memory        # open TUI
fellowship mem           # alias

The TUI has four views: Dashboard (stats overview), Runs (full run history), Memory (browse learnings, gotchas, decisions, reviews), and Diff (side-by-side diff per run). Navigate with vim keys (jk) or arrow keys. See the Commands reference for all keyboard shortcuts.

Security

Fellowship includes prompt injection protection:

• 30+ detection patterns — XML tags, ChatML tokens, role markers, identity overrides, authority markers
• Sanitization on every run — Learnings, gotchas, and architecture scanned before injection
• fellowship sanitize — Manual scan with severity levels
• Dry-run reports — --dry-run shows sanitization results before committing to a run
• strictMode — Optional throw-on-detection for zero-tolerance environments

Skills System

Fellowship ships with built-in skills and supports project-level overrides:

fellowship/skills/          ← Built-in (shipped with CLI)
  code-review.md            ← Sentinel's review guidelines

.fellowship/skills/         ← Project overrides (optional)
  code-review.md            ← Your custom review guidelines

Project skills override built-in skills with the same name. Profiles reference skills with {{skill:name}}.

Platform Support

Supported Providers