Yaggo Brain

yaggo-brain

A FOSS, local-first "brain" / control plane for AI-assisted software projects. Living memory, code & knowledge graphs, vectorless + vector RAG, cost-aware model routing, self-improving skills, a catalog of permissioned agents, quality/eval loops, a hardened sandbox, and shared collective memory — all wired into your IDE through the Model Context Protocol (MCP).

[](./LICENSE)

Read this in other languages: English · [Español](./README.es.md) · [Documentation](./docs/README.md)

> What it is. yaggo-brain is not a single MCP server — it is a full control plane > that turns the scattered artifacts of an AI-assisted project (code, docs, decisions, > lessons, costs, evals, agent runs) into a queryable, self-improving memory. Your > coding agent (Cursor, Claude Code, Windsurf, Codex, Gemini CLI, ...) talks to it over > MCP and gets compact, citeable context instead of re-reading your repo file by file.

> Local-first & private. Everything runs on your machine: Postgres (with Apache AGE > + pgvector), Valkey, Ollama, and LiteLLM via Docker Compose. No API keys are required > for the local tier; your code and memory never leave your machine unless you explicitly > opt in to the community Hub.

---

Table of contents

• [Why yaggo-brain](#why-yaggo-brain)
• [Shared & collective memory](#shared--collective-memory)
• [How it differs from a code-graph MCP](#how-it-differs-from-a-code-graph-mcp)
• [Architecture](#architecture)
• [Features](#features)
• [Quick start](#quick-start)
• [Configuration](#configuration)
• [MCP tools (3-layer)](#mcp-tools-3-layer)
• [Agent catalog](#agent-catalog)
• [The panel](#the-panel)
• [Tech stack](#tech-stack)
• [Project status](#project-status)
• [Contributing](#contributing)
• [License](#license)
• [Acknowledgments](#acknowledgments)

---

Why yaggo-brain

• Living memory, not just retrieval. A five-layer memory hierarchy (Global lessons →

Workspace → Project → Run → Prompt context) plus editable, Letta-style memory blocks. Lessons are extracted from failures, promoted with evidence, and reused across sessions.

• Two graphs, one brain. A knowledge graph (wiki, decisions, lessons, documents) and

a code graph (functions, calls, routes) built with tree-sitter on top of Apache AGE, with an optional pluggable code-graph backend.

• Hybrid RAG. pgvector similarity search fused with a PageIndex-style vectorless

tree walk, so answers come back with clickable citedIds.

• Cost-aware by default. A model router selects a tier (local-fast on Ollama →

cloud) per task; every call is metered into a cost dashboard with budgets.

• Agents with real permissions. A YAML catalog of 14 agents, each gated by a

permission matrix (read/write/execute), per-run budgets, and lifecycle hooks.

• Quality & evals in the loop. A Quality Agent (LangGraph) evaluates → reflects →

records lessons → optionally triggers nightly autoresearch that only ships a skill change if a fixed metric improves. Promptfoo + RAGAS suites gate regressions in CI.

• Hardened sandbox. Agent-written changes run in an ephemeral Docker runner

(seccomp, read-only rootfs, command guard + audit) and land as a reviewable diff.

• Multi-IDE, one install. yaggo-brain install detects your harness and wires MCP

entries, instruction files, and hooks for Cursor, Claude Code, Windsurf, and more.

---

Shared & collective memory

Memory in yaggo-brain is designed to be shared — across agents, across a team, and (optionally) across the community.

1. Shared across agents and layers

All agents read and write the same memory substrate:

| Layer | Scope | Examples | |-------|-------|----------| | L1 Global lessons | all projects | reusable, generalized lessons (opt-in seed pack in git) | | L2 Workspace | one workspace | conventions, personas, budgets | | L3 Project | one project | project context, decisions, wiki, code graph | | L4 Run | one agent run | reflexions, tool traces, findings | | L5 Prompt context | one prompt | the compacted context actually sent to the LLM |

Editable memory blocks (human, persona, project_context, ...) are shared state that any agent can read via memory_get and update via update_memory_block — the same block informs every subsequent agent, so learning compounds instead of resetting.

2. Shared across a team (graph artifact)

The code/knowledge graph can be exported as a single compressed artifact committed next to your source, so a teammate who clones the repo skips the full re-index and only fills in their local diff. This pattern is inspired by codebase-memory-mcp's team-shared graph artifact and by graphify's graphify-out/ directory.

3. Shared across the community (the Hub, opt-in)

The yaggo-brain Hub lets you contribute a lesson upstream. It is opt-in and local-first by default:

1. yaggo-brain contrib --lesson-id=... submits a lesson (needs HUB_OPT_IN=true).
2. The Hub pipeline generalizes it (strips project specifics), runs eval gates,

and only then appends it to the git-committed pack packages/hub/seed/community-lessons.json.

1. yaggo-brain update pulls the latest community lessons back into your L1 layer.

The bootstrap loop (no cloud required). The community pack lives in git. When a contribution is accepted it is written to packages/hub/seed/community-lessons.json; commit it, and anyone who clones the repo and runs pnpm db:migrate loads that shared memory into their database automatically — so the collective knowledge feeds every new checkout and compounds over time, fully offline and private.

Repo-as-hub (network effect, no server). The community pack also lives in its own public repo, YaggoSEO/yaggo-brain-community. yaggo-brain update pulls it (raw JSON over HTTPS) and refreshes your local seed pack, so pnpm db:migrate loads it — a shared, self-improving memory across everyone who uses it, running entirely on git. Contribute back with a pull request. Override the source with HUB_URL (a raw .json pack or an API base); it falls back to the local API, then the default community repo.

Aggregated, k-anonymized (k ≥ 5) telemetry can optionally power a public Observatory (learning curves, costs, model cookbook) — never raw code, never per-user data.

---

How it differs from a code-graph MCP

yaggo-brain is often compared to focused code-graph MCP servers such as codebase-memory-mcp (an excellent, blazing-fast, single-binary code intelligence engine). They solve different problems and compose well together:

| | Code-graph MCP (e.g. codebase-memory-mcp) | yaggo-brain | |---|---|---| | Primary goal | Fast structural code graph for agents | Full project brain / control plane | | Memory | The code graph | 5-layer living memory, lessons, reflexions, memory blocks | | Retrieval | Structural + semantic over code | Code graph + knowledge graph + hybrid (vector + vectorless) RAG over docs/wiki | | Cost | n/a | Model router + cost metering + budgets | | Agents | The client agent is the intelligence | Built-in catalog of 14 permissioned agents + quality/eval loop | | Writes | Read-only analysis | Sandboxed agent writes → diff review → git branch | | Shared memory | Team graph artifact | Team graph artifact + community Hub (opt-in) | | Footprint | Single static binary | Docker Compose stack (Postgres/AGE/pgvector, Valkey, Ollama, LiteLLM) |

They are complementary. yaggo-brain treats a code-graph engine as one pluggable backend for its code intelligence (CODE_INTEL_BACKEND=hybrid|age|cbm) and layers memory, RAG, cost, agents, evals, and a panel on top. Use the code-graph MCP when you want a fast, zero-dependency graph; use yaggo-brain when you want the whole lifecycle.

---

Architecture

A pnpm + Turborepo monorepo.

flowchart LR
  IDE["Coding agent(Cursor / Claude Code / Windsurf / ...)"] -- MCP --> MCP["mcp-server (stdio)+ worker HTTP mirror"]
  IDE -- hooks --> WK
  Web["web (Next.js panel)"] -- REST/SSE --> API["api (NestJS)"]
  MCP --> API
  WK["worker (BullMQ jobs + crons)"] --> DB[("PostgresApache AGE + pgvector")]
  API --> DB
  API --> RT["model-router → LiteLLM → Ollama / cloud"]
  WK --> VEC["vectors-worker (UMAP)"]
  WK --> DOC["docling-worker (PDF)"]
  WK --> RAG["ragas-worker (faithfulness)"]
  API --> SBX["sandbox-runner (Docker, seccomp)"]

Apps

| Path | Role | |------|------| | apps/web | Next.js panel (Explorer, Graph, Knowledge, Wiki, Docs, Vectors, Costs, Cookbook, Hub, Memory, Decisions, Workflow, Terminal, Agents, Lessons, Quality, Review, Skills) | | apps/api | NestJS REST API + SSE + Better Auth | | apps/worker | BullMQ background jobs, crons, and the MCP HTTP mirror (:37700) | | apps/mcp-server | MCP stdio server (3-layer tools) | | apps/mcp-proxy | Routes MCP tool calls between a local worker and a remote instance | | apps/observatory | Static public aggregates site | | apps/sandbox-runner | CLI entry for sandboxed command execution | | apps/yaggo-brain-cli | install, doctor, wrap, update, contrib |

Packages (selected)

project-schema (Drizzle schema + migrations + queue types), model-router, cost-engine, rag, graph, code-intel, memory, lessons, agent-runtime, quality-agent, evals, skills, hooks, hub, observatory-data, auth, privacy, sandbox, mcp-tools, visual-panel-types, ui.

Infra (Docker Compose)

Postgres (AGE + pgvector), Valkey, Ollama, LiteLLM, Langfuse, plus Python workers for UMAP vectors, RAGAS faithfulness, and Docling PDF parsing.

---

Features

Memory & knowledge

• Five-layer memory hierarchy + editable memory blocks
• Lessons with proposed → accepted promotion on repeated evidence
• Knowledge graph aggregating wiki, decisions, lessons, and documents
• Architecture Decision Records ingested from docs/adr/*.md

Code intelligence

• tree-sitter code graph on Apache AGE (functions, calls, routes)
• Pluggable backend: CODE_INTEL_BACKEND=hybrid|age|cbm
• code_search, code_trace_path, code_detect_changes

Retrieval (RAG)

• Hybrid retrieval: pgvector chunks + PageIndex-style vectorless tree scoring
• Answers with clickable citedIds; A/B model compare
• Document ingestion via Docling (with a pymupdf fallback)
• UMAP vector snapshots for the Vectors view

Cost & routing

• Model router with tiers (local-fast on Ollama → cloud), hardware-aware cookbook
• Per-call metering, budgets, and a cost dashboard

Agents, quality & evals

• 14-agent YAML catalog with a permission matrix, per-run budgets, and lifecycle hooks
• Quality Agent (LangGraph): evaluate → reflect → record lesson → check pattern → autoresearch
• Nightly skill autoresearch that only ships an improvement if a fixed metric goes up
• Promptfoo + RAGAS eval suites with a CI regression gate

Security

• Better Auth (email/password, scoped bearer tokens); AUTH_DISABLED=true for local dev
• Postgres Row-Level Security scoped by workspace
• `` redaction + read-time filtering; redacted chunks excluded from snapshots
• Ephemeral Docker sandbox (seccomp, cap-drop, read-only rootfs), command guard + audit

Integration

• Multi-IDE install (Cursor, Claude Code, Windsurf, and more) via native config + hooks
• MCP 3-layer tools designed for minimal token footprint
• doctor health checks and wrap scripts for proxying

---

Quick start

One-line install

The installer bootstraps the whole stack: it clones the repo, installs dependencies, brings up the Docker infrastructure, applies migrations, and pulls the local models.

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/YaggoSEO/yaggo-brain/main/install.sh | bash
# options: | bash -s -- --dir=./yaggo-brain --no-models --no-docker

Windows (PowerShell):

# 1. Download the installer
Invoke-WebRequest -Uri https://raw.githubusercontent.com/YaggoSEO/yaggo-brain/main/install.ps1 -OutFile install.ps1
# 2. (Recommended) inspect it
notepad install.ps1
# 3. Run it
.\install.ps1

Then start it with pnpm dev. yaggo-brain is a full local-first stack (Docker Compose + a pnpm monorepo), not a single binary, so the installer sets up the stack rather than dropping an executable. Prefer to do it by hand? Follow the manual steps below.

Prerequisites

• Node.js >= 20 and pnpm 9+ (repo pins pnpm@11.9.0)
• Docker Desktop (WSL2 backend recommended on Windows)
• Git

Install & run

pnpm install
cp .env.example .env

# Start infra: Postgres (AGE + pgvector), Valkey, Ollama, LiteLLM, Langfuse, workers
pnpm db:up

# Apply migrations + seed the default workspace
pnpm db:migrate

# Start web (:3000) + api (:3333) + worker (:37700). This terminal stays open.
pnpm dev

• Panel:
• API:

Local models (Ollama)

docker exec yaggo-ollama ollama pull nomic-embed-text
docker exec yaggo-ollama ollama pull qwen2.5:3b
docker exec yaggo-ollama ollama pull qwen2.5-coder:7b

Connect it to your IDE (MCP)

# stdio MCP in a separate terminal
pnpm dev:mcp

# or auto-detect your harness and wire MCP + hooks
npx yaggo-brain install --target=cursor   # also: claude-code, windsurf, --all
npx yaggo-brain doctor --json

Then, in your agent, say "Index this project" and start asking questions — hits come back compact and citeable.

---

Configuration

Copy .env.example to .env. Key variables:

| Variable | Default | Purpose | |----------|---------|---------| | DATABASE_URL | postgres://yaggo:yaggo@localhost:55432/yaggo | Postgres | | REDIS_URL | redis://localhost:6379 | BullMQ / Valkey | | LITELLM_BASE_URL | http://localhost:4000 | LLM gateway | | OLLAMA_BASE_URL | http://localhost:11434 | Local models | | ASK_MODEL | qwen2.5:3b | Default local answer model | | AUTH_DISABLED | true | Disable auth for local dev | | PAGE_INDEX_ENABLED | true | Vectorless tree retrieval in /ask | | DOCLING_ENABLED | false | Use Docling worker for PDFs (fallback: pymupdf) | | SANDBOX_MODE | stub | stub skips Docker; unset to use the real runner | | CODE_INTEL_BACKEND | hybrid | hybrid \| age \| cbm |

See .env.example for the full list (auth, storage, proxy, cloud provider keys).

---

MCP tools (3-layer)

Tools follow a progressive-disclosure pattern so agents spend as few tokens as possible:

• Layer 1 — *_search: compact hits { id, title, citedId } + citedIds
• Layer 2 — *_timeline: chronological context around an anchor
• Layer 3 — *_get: full content for a set of citedIds

Coverage spans memory, lessons, observations, wiki, decisions, and code, plus get_vector_neighbors, code_search, feedback tools (including update_memory_block, record_observation, request_reflexion), and get_agents. The stdio server and the worker HTTP mirror (POST /api/tools/* on :37700) expose the same surface.

---

Agent catalog

14 agents live as YAML in packages/agent-runtime/src/agents/, each with a permission matrix, allowed tools, subscribed hooks, and budgets:

| Agent | Mode | Role | |-------|------|------| | architect | read-only | Architecture & risk analysis | | documentation | read-only | Docs/wiki generation | | research-agent | read-only | Multi-source research over the graph | | reviewer-agent | read-only | Code/PR review | | security-agent | read-only | Security review | | backend-engineer | write (sandbox) | Backend changes via git worktree | | frontend-engineer | write (sandbox) | Frontend changes via git worktree | | devops-agent | write (sandbox) | Infra/CI changes | | seo-geo-engineer | write (sandbox) | SEO/GEO changes | | qa | write (sandbox) | Writes tests, runs them

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: YaggoSEO
• Source: YaggoSEO/yaggo-brain
• License: MIT

Install and usage instructions live in the source repository linked above.