Archon OS: The Open-Source Brain That Makes Claude Code Remember

AI coding assistants have a memory problem. You hand Cursor a codebase on Monday, it's brilliant. You come back Wednesday with a related task, and it's read half the docs again, forgotten the architecture decisions, and "helpfully" reinvented a pattern you explicitly rejected.

Archon is trying to fix that. Built by coleam00 and the Dynamous AI Mastery community, it's an open-source knowledge and task management backbone for AI coding assistants — a persistent, self-hosted brain your agents plug into via the Model Context Protocol (MCP). As of April 2026, the repo sits at 13.7K stars and is actively in beta under v0.1.0.

What Archon actually is (and isn't)

Archon is not another coding agent. It doesn't write code. It's the layer between your agents and everything they need to remember.

Under the hood, Archon is four microservices:

• archon-ui (port 3737) — React + Vite + TailwindCSS dashboard
• archon-server (port 8181) — FastAPI + Socket.IO, handles crawling, ingestion, and core business logic
• archon-mcp (port 8051) — the MCP server your AI client connects to
• archon-agents (port 8052) — PydanticAI-powered operations like reranking and RAG

A Supabase/PostgreSQL instance with PGVector stores the knowledge base. An optional fifth service, archon-agent-work-orders (port 8053), orchestrates Claude Code CLI workflows.

Important context: the project pivoted. The old Archon was "the AI agent that builds other agents" — the agenteer. The current v0.1.0 beta throws that out and becomes knowledge/task infrastructure instead. coleam00 openly acknowledges this in the README: "This new vision for Archon replaces the old one."

The four things it does that matter

1. Smart web crawling. Point Archon at a docs site and it figures out sitemaps, crawls the tree, and chunks the content intelligently. Try https://ai.pydantic.dev/llms.txt as a first test.

2. Document ingestion. Upload PDFs, Word docs, markdown, or plain text. Archon processes them with contextual embeddings and automatically indexes code examples separately — so when your agent searches "how does FastAPI handle dependency injection," it gets the code block, not a paragraph describing it.

3. Task management with AI awareness. Projects, features, tasks — a hierarchical workflow where each item is linked to the knowledge base. Your AI agent can both read tasks and update them as work progresses.

4. MCP-native integration. This is the unlock. Once Archon is running, any MCP-compatible client — Claude Code, Cursor, Kiro, Windsurf, Claude Desktop — can tap into the same knowledge and task state. You and your agents work against one source of truth.

Running it locally

Setup is Docker-based and takes roughly ten minutes if you already have Supabase credentials:

# 1. Clone the stable branch
git clone -b stable https://github.com/coleam00/archon.git
cd archon

# 2. Configure environment
cp .env.example .env
# Edit .env with your Supabase URL and service key

# 3. Run the migration SQL
# Copy migration/complete_setup.sql → paste into Supabase SQL Editor → execute

# 4. Start everything
docker compose up --build -d

Open http://localhost:3737 and you'll hit an onboarding flow that asks for an OpenAI, Gemini, or Ollama API key. LLM choice is swappable — not locked to OpenAI.

Prerequisites (the actual list from the README, not a guess):

• Docker Desktop
• Node.js 18+ (only for hybrid dev mode)
• A Supabase account — free tier is fine, or run Supabase locally
• An LLM API key

Linux users may need sudo usermod -aG docker $USER to avoid permission errors. Windows users will want WSL2 for Make support, though Make is optional.

The architecture, in one diagram

┌───────────────┐   ┌───────────────┐   ┌───────────────┐
│  Frontend UI  │←→ │  Server (API) │←→ │  MCP Server   │
│  React + Vite │   │  FastAPI+IO   │   │  HTTP wrapper │
│  :3737        │   │  :8181        │   │  :8051        │
└───────────────┘   └───────────────┘   └───────────────┘
         │                  │                    │
         └──────────────────┼────────────────────┘
                            ▼
                   ┌──────────────────┐
                   │  Supabase/PG     │
                   │  + PGVector      │
                   └──────────────────┘

Services communicate over HTTP. No shared code. The MCP server is a lightweight wrapper that translates between the MCP protocol and the server's internal APIs. That separation means you can scale the ingestion pipeline independently of the MCP endpoint — which matters once you're crawling gigabytes of docs.

What's good, what's rough

Good:

• Multi-LLM from day one. OpenAI, Gemini, Ollama — your choice, swappable through the UI.
• Real-time UX. Socket.IO streams crawl progress, task updates, and agent responses live.
• Hybrid dev mode. make dev runs backend in Docker and frontend local with hot reload. Good DX for contributors.
• License is sane. Archon Community License (ACL) v1.2 — use it freely, fork it, just "don't sell it as-a-service without permission."

Rough (and the README says so):

• Beta means beta. 106 open issues, 45 open pull requests. Expect things to break.
• Supabase dependency. Not everyone wants to manage a Supabase project. A lighter-weight SQLite + embedded vector store option would widen the audience significantly.
• No hosted version. You're running this yourself, full stop.
• Docs live mostly in the README. A dedicated docs site would help onboarding at scale.

Why this matters more than it looks

There's been a quiet realization across AI coding tool teams: the bottleneck isn't model capability, it's context. Claude Opus 4.7 and GPT-5.4 can both write excellent code when they know what you're building. They both flail when they don't.

The short-term industry response has been ever-larger context windows — Gemini 3.1 Pro shipped with 2M tokens, and everyone chased it. But stuffing an entire codebase into a prompt is expensive, slow, and still loses things.

Archon's bet is different: structured, persistent, searchable context you own and curate, queried on demand via MCP. That's closer to how humans work. You don't re-read every doc every morning. You know where to look.

If that model wins, tools like Archon — or something like it, self-hosted or otherwise — become the default middleware for AI-assisted development. It's early, the beta is rough, but the shape of the answer is visible.

The Bottom Line

Archon is what happens when someone decides AI coding assistants should stop being amnesiac. It's not perfect — the Supabase requirement is heavy and the beta has sharp edges — but 13.7K stars say developers want this, and the MCP-first architecture means you're not locked into any single AI vendor. Self-host it, point Claude Code at it, and watch your agent actually remember what you told it yesterday.