# Yaggo Brain

> FOSS local-first brain / control plane for AI-assisted projects: living memory, code & knowledge graphs, hybrid RAG, cost-aware model routing, a permissioned agent catalog, quality/eval loops, a hardened sandbox, shared collective memory, and multi-IDE MCP integration.

- **Type:** MCP server
- **Install:** `agentstack add mcp-yaggoseo-yaggo-brain`
- **Verified:** Pending review
- **Seller:** [YaggoSEO](https://agentstack.voostack.com/s/yaggoseo)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [YaggoSEO](https://github.com/YaggoSEO)
- **Source:** https://github.com/YaggoSEO/yaggo-brain

## Install

```sh
agentstack add mcp-yaggoseo-yaggo-brain
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://github.com/DeusData/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`.
3. `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](https://github.com/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](https://github.com/DeusData/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.

```mermaid
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:**

```bash
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):**

```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

```bash
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)

```bash
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)

```bash
# 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](https://github.com/YaggoSEO)
- **Source:** [YaggoSEO/yaggo-brain](https://github.com/YaggoSEO/yaggo-brain)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-yaggoseo-yaggo-brain
- Seller: https://agentstack.voostack.com/s/yaggoseo
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.