⚔️ Fellowship

Your AI agents remember everything — and share what they learn.

Fellowship is a CLI that gives AI coding agents a persistent Memory Graph. Every run, agents consult accumulated knowledge before writing a single line of code. Every decision, gotcha, and lesson is stored and reused.

Works with Claude Code, Codex, and any CLI-based AI coding agent.

The Problem

AI coding agents are powerful but stateless. Every session starts from zero:

• They forget you already fixed that Supabase connection bug
• They ignore the architectural decision you made last week
• They repeat the same mistakes across runs
• A new team member (or clone) starts with zero context

The Solution: Memory Graph

Fellowship maintains a local SQLite graph that grows with every run. Nodes are learnings, gotchas, decisions, and code patterns. Edges are relationships between them.

Before every run, the agent must search the graph. Before writing code, it must query it again. Knowledge accumulates and compounds.

Run 1: Agent discovers Supabase requires pooler=false for direct connections
       → Recorded as gotcha in Memory Graph

Run 5: Different agent, different task, same project
       → graph_search finds the gotcha before writing DB code
       → No bug. No wasted time.

This is not RAG. There's no vector database. No embeddings. The graph is pure SQLite with FTS5 — runs locally, zero infra, commits to your repo.

Quick Start

npm install -g fellowship-cli

# New project
mkdir my-api && cd my-api && git init
fellowship init

# Existing project
cd my-existing-project
fellowship adopt

# Run a task
fellowship run "add user authentication with JWT"

How It Works

fellowship run "add search endpoint"
        │
        ▼
┌─────────────────┐
│  graph_search   │  ← MANDATORY: agent searches Memory Graph before anything else
│  graph_query    │  ← MANDATORY: minimum 2 queries before writing code
└────────┬────────┘
         │  "Found: 3 learnings, 1 gotcha about Supabase RLS"
         ▼
┌─────────────────┐
│  Spec Engine    │  ← Generates spec using graph context (skips architecture.md if MCP available)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Smart Selector │  ← Picks the right agent: confidence scoring + LLM fallback
└────────┬────────┘
         │  "frontend task → DaVinci (frontend-engineer)"
         ▼
┌─────────────────┐
│  Agent (Code)   │  ← Writes code in isolated git worktree
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  MCP Recording  │  ← Agent records learnings/gotchas/decisions DURING run
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Sentinel       │  ← AI reviewer checks code against spec
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Learn & Push   │  ← Graph enriched, PR created, team notified
└─────────────────┘

Key detail: Your working directory never changes. Fellowship creates an isolated git worktree for each run — you stay on your branch the whole time.

Memory Graph

Node Types

| Type | What it stores | Example | |------|----------------|---------| | learning | General lessons from experience | "Always use parameterized queries" | | gotcha | Technical traps with specific fix | "Supabase pooler breaks direct connections — use port 5432" | | decision | Architectural choices with rationale | "Chose JWT over sessions: stateless, scales horizontally" | | code-pattern | Reusable implementation patterns | "Auth middleware pattern for Express routes" | | architecture | System-level structural knowledge | "Event-driven: services communicate via queues, not HTTP" |

MCP Tools (available to agents during runs)

graph_search(query: string)           // FTS5 full-text search across all nodes
graph_query(query, type?, limit?)     // Filtered query by node type
record_learning(content, source?)     // Add a new learning
record_gotcha(content, source?)       // Add a new gotcha
record_decision(content, source?)     // Add a new decision

Mandatory Protocol

Every agent run follows this protocol (enforced in agent prompt):

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

Browse the Graph

fellowship memory          # Interactive TUI
fellowship mem             # Alias
fellowship search "auth"   # Full-text search

Smart Agent Selection

Fellowship picks the right specialist for each task — not just the first agent in the list.

How it works:

1. Keyword scoring against each agent's role and scope (weighted by role templates)
2. Confidence calculation: winner score vs runner-up gap
3. If confidence < 0.4 → LLM fallback with minimal context (20 tokens, temperature 0)
4. Graceful fallback if LLM fails

Result: Frontend tasks go to frontend agents. Backend tasks to backend. No more wrong assignments.

# team.yaml — define clear roles and scopes for best results
agents:
  - id: frontend-engineer
    role: Frontend Developer
    scope: UI components, pages, CSS, React, Next.js, user interactions
  - id: backend-engineer
    role: Backend Developer
    scope: APIs, database, auth, server logic, migrations

Commands

fellowship init

Interactive wizard for new projects. Analyzes description, generates architecture, creates agent team.

fellowship adopt

Adds Fellowship to an existing project. Detects stack, framework, patterns.

fellowship run <task>

Core command. Graph search → spec → agent → review → learn.

fellowship run "add pagination to GET /users"
fellowship run "refactor auth middleware" --review
fellowship run "add search endpoint" --bg
fellowship run "add auth" --bg --review
fellowship run --spec path/to/spec.md
fellowship run "add search" --agent backend-engineer  # force specific agent

| Flag | Description | |------|-------------| | --bg | Background run — free terminal, get notified when done | | --review | Pause for human review after implementation | | --dry-run | Preview spec only, no code changes | | --no-review | Skip Sentinel AI review | | --spec <path> | Use existing spec | | --agent <id> | Force a specific agent (bypass smart selector) |

fellowship fix [description]

Diagnose a bug, generate a fix spec, and run it.

fellowship fix "404 after creating a new lore — redirect broken"

fellowship memory / fellowship mem

Interactive TUI: Dashboard, Runs, Memory (learnings/gotchas/decisions/reviews), Diff.

fellowship memory
fellowship memory --view memory --section gotchas
fellowship memory --search "database"

fellowship spec <task>

Generate a spec without running it.

fellowship status

Dashboard: team, recent runs, costs, stats.

fellowship learn <lesson>

Manually add a learning to the Memory Graph.

fellowship learn "Always use parameterized queries — never string interpolation for SQL"

fellowship search <query>

Full-text search across all graph nodes.

fellowship search "supabase connection"

fellowship doctor

Check setup: Node, Git, agent CLI, API key, config, team. Zero LLM calls.

fellowship scribe

Generate/update project documentation from code changes.

fellowship sanitize

Scan .fellowship/ files for prompt injection attempts.

fellowship hire

Add a new agent to your team via AI conversation.

fellowship connect

Configure AI provider credentials (stored in system keychain).

Configuration

.fellowship/config.yaml

name: my-api
created: '2026-03-11'

ai:
  provider: anthropic
  model: claude-sonnet-4-6
  envVar: ANTHROPIC_API_KEY

review:
  enabled: true
  model: claude-haiku-4-5-20251001
  strictness: balanced        # strict | balanced | lenient
  maxCycles: 2

hooks:
  onComplete:
    - { sound: done }
    - { notify: desktop }
    - { notify: telegram }
  telegramBotToken: "..."     # or env FELLOWSHIP_TELEGRAM_BOT_TOKEN
  telegramChatId: "..."       # or env FELLOWSHIP_TELEGRAM_CHAT_ID
  sounds: true
  desktop: true

scribe:
  enabled: false
  autoRun: false
  outputs: [changelog, readme]

security:
  sanitize: true
  strictMode: false

Project Structure

.fellowship/
├── config.yaml          ← Provider, model, hooks, review settings
├── team.yaml            ← Agent definitions (roles, models, scopes)
├── profiles/            ← Agent system prompts
├── fellowship.db        ← SQLite: Memory Graph + runs + decisions
├── specs/               ← Auto-generated specs (one per run)
├── mcp.log              ← MCP server log (graph operations)
├── learnings.md         ← Raw learnings extracted from runs
├── learnings-distilled.md ← Top 30 distilled learnings (in agent prompt)
├── gotchas.md           ← Technical pitfalls and fixes
└── architecture.md      ← Project architecture reference

What to commit: config.yaml, team.yaml, profiles/, learnings.md, gotchas.md, architecture.md, specs/

What to gitignore: fellowship.db (binary), mcp.log

Coming in v0.6: fellowship export — snapshot the Memory Graph as .jsonl.gz and commit it. Clone the repo, run fellowship import, and agents start with full knowledge from day one.

Notifications

Zero config on all platforms.

| Platform | Sounds | Desktop | |----------|--------|---------| | macOS | afplay | osascript | | Linux | paplay/aplay | notify-send | | Windows | PowerShell | PowerShell toast |

Plus Telegram, Slack, and custom shell hooks via hooks: in config.

Supported Providers

| Provider | Agent CLI | Models | |----------|-----------|--------| | Anthropic | Claude Code | claude-sonnet-4-6, claude-opus-4-6 | | OpenAI | Codex | gpt-4o, o3-mini |

Requirements

• Node.js >= 18
• Git
• Claude Code (claude) or Codex (codex)

Changelog

v0.5.2 (March 2026)

• Smart agent selector — Confidence scoring + LLM fallback. Right agent, every time.
• Mandatory graph protocol — Agents must search and query Memory Graph before writing code.
• Mandatory MCP recording — Learnings, gotchas, decisions recorded during runs, not after.
• Reduced LLM calls — 9 → 2 per run. Node classification without LLM.
• fellowship fix — New command to diagnose and fix bugs with one command.
• fellowship memory TUI — Interactive browser for runs, memory, and diffs.
• MCP log fix — Inline logs now appear correctly during runs.

v0.4.x

• Memory Graph via MCP (SQLite + FTS5)
• Multiple provider support (Claude, Codex)
• Background runs with notifications
• Sentinel AI reviewer
• Scribe documentation generation

License

MIT

Built with ⚔️ by MiniGalaxyMage