What is Ragbot?
Ragbot is the chat-led runtime of synthesis engineering — the open methodology for systematic human-AI collaboration on complex work. It is the workbench where humans and AI do the crafts of synthesis one collaborative turn at a time, on the user's own workspace, with skills, agent execution, durable memory, and bi-directional MCP. Workspace-aware. Local-first with frontier fallback. Production-grade observability. MIT-licensed.
What's new in v3.5 (May 2026)
Three releases shipped over the past month — v3.3 (local Gemma 4 as first-class), v3.4 (the next-major-features release), and v3.5 (substrate cleanup) — compose into one architectural shift: Ragbot is now the conversational reference runtime of synthesis engineering, with a hand-rolled agent loop, bi-directional MCP, an executable SKILL.md runtime, cross-workspace synthesis with confidentiality and audit, three-tier memory, and OpenTelemetry observability.
Key Features
Workspace-aware retrieval
Ragbot reads ai-knowledge-* repositories under your workspaces directly. Multiple workspaces compose; confidentiality boundaries are explicit. PostgreSQL + pgvector with native full-text search (since v3.5, pgvector is the only backend).
Hand-rolled agent loop
A graph-state agent loop replaces single-turn chat: the agent answers directly, dispatches retrieval, calls tools, runs skills, or fans out to sub-agents. Plan-and-Execute and lead-agent-with-sub-agents patterns. Deterministic replay via ragbot agent replay. No framework dependency.
SKILL.md runtime
Ragbot discovers and indexes Agent Skills — portable, file-based capabilities defined by SKILL.md. The same skill format runs in Claude Code, Codex CLI, Cursor, Gemini CLI, and Ragbot. No re-authoring per tool.
Bi-directional MCP
Ragbot is both an MCP client implementing all six primitives (tools, resources, prompts, Roots, Sampling, Elicitation) plus Tasks, and an MCP host exposing retrieval, skills, and agent dispatch to other agents. Integration is a protocol concern, not a fork concern.
Cross-workspace synthesis
Reason across multiple workspaces in a single turn with per-workspace confidentiality tags (public / personal / client-confidential / air-gapped), per-workspace model routing via routing.yaml, and an append-only audit log of every cross-workspace operation.
Local-first with frontier fallback
Run local Gemma 4, Qwen3, DeepSeek-V3, Llama 4, or Mistral Large via Ollama for sensitive work; switch to Anthropic, OpenAI, or Google frontier models when capability matters. Swappable LLM backend layer — LiteLLM or direct SDKs.
Three-tier durable memory
Vector RAG, entity-graph memory with provenance, and per-user session state — with an idempotent consolidation pass that distills durable facts between sessions. Filesystem-as-source-of-truth under ~/.synthesis/. State survives restarts; nothing hidden inside a service.
Production-grade observability
OpenTelemetry traces with semantic GenAI attributes (export to Phoenix, Langfuse, Datadog, or Honeycomb), Prometheus metrics with prompt-cache stats, structured logging surfaced under uvicorn, and an isolated demo mode for safe screenshots and audience-facing evaluation.
Quick Start
Try Ragbot end-to-end in a few minutes — demo mode ships a bundled workspace so you can evaluate without any local setup.
# Clone the repository
git clone https://github.com/synthesisengineering/ragbot.git
cd ragbot
# Set at least one API key
cp .env.example .env
# Edit .env — Anthropic, OpenAI, or Google. # Or run fully local with Ollama (no API key required). # Install Python deps
pip install -r requirements.txt
# Start the Postgres + ragbot stack
docker compose up -d
# Run any subcommand in demo mode (isolated bundled workspace)
RAGBOT_DEMO=1 python3 src/ragbot.py chat -p "What is ragbot?"
# Or launch the Web UI
RAGBOT_DEMO=1 python3 -m uvicorn src.api.main:app --port 8000 &
cd web && npm install && NEXT_PUBLIC_API_URL=http://localhost:8000 npm run dev
# Open http://localhost:3000 To run against your own workspaces instead of the demo content, unset RAGBOT_DEMO and follow the full setup guide on GitHub.
Ragbot in the Synthesis Engineering Ecosystem
Ragbot is a reference implementation of the synthesis-engineering methodology, focused on the conversational interaction primitive.
Sibling reference implementations cover other primitives:
synthesis-console for direct manipulation (browse and edit),
Ragenie for the procedural primitive (workflow definition with autonomous execution),
and synthesis-skills as the portable capability format consumed by every runtime and by external SKILL.md-compatible agents (Claude Code, Codex CLI, Cursor, Gemini CLI).
The family of reference implementations will grow as the methodology and the AI landscape evolve.
All implementations share the ~/.synthesis/ config home, the ai-knowledge-* workspace model, and a Python substrate library, and they integrate through Model Context Protocol (MCP) calls and a filesystem-as-source-of-truth contract.
Resources
- GitHub Repository
Source code, documentation, releases, and issue tracking.
- Synthesis Engineering
The methodology: open practices for systematic human-AI collaboration on complex work.
- Synthesis Coding
The coding craft within synthesis engineering — applied to building Ragbot itself.
- Articles
Notes from the Ragbot project: design decisions, release write-ups, and field reports.