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).

Read this in other languages: English · Español · Documentation

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
• Shared & collective memory
• How it differs from a code-graph MCP
• Architecture
• Features
• Quick start
• Configuration
• MCP tools (3-layer)
• Agent catalog
• The panel
• Tech stack
• Project status
• Contributing
• License
• 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.
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. 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<br/>(Cursor / Claude Code / Windsurf / ...)"] -- MCP --> MCP["mcp-server (stdio)<br/>+ worker HTTP mirror"]
  IDE -- hooks --> WK
  Web["web (Next.js panel)"] -- REST/SSE --> API["api (NestJS)"]
  MCP --> API
  WK["worker (BullMQ jobs + crons)"] --> DB[("Postgres<br/>Apache 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)"]

Loading

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
• <private> 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: http://localhost:3000
• API: http://localhost:3333

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 in the sandbox
cost-controller	persistent	Watches spend, enforces budgets
lessons-curator	persistent	Curates and promotes lessons
observation-compressor	persistent	Compresses observations at session end
quality	persistent	Quality loop: evaluate → reflect → lesson

Write agents produce a diff that must be approved in the Review tab before it lands on a new git branch; rejecting a diff records a lesson.

---

The panel

The Next.js panel exposes the whole brain as tabs: Explorer, Graph, Knowledge, Wiki, Docs, Vectors, Costs, Cookbook, Hub, Memory (live observations + block editor), Decisions, Workflow, Terminal, Agents (kanban board), Lessons, Quality, Review, and Skills — plus /login and a connected-IDEs dashboard.

---

Tech stack

TypeScript across the board. Next.js (panel), NestJS (API), BullMQ on Valkey (jobs), Drizzle ORM on Postgres with Apache AGE + pgvector, tree-sitter (code parsing), LangGraph.js (agent graphs), LiteLLM + Ollama (model gateway + local inference), Better Auth (auth), Docling (PDF), RAGAS + Promptfoo (evals), Langfuse (observability), and the MCP TypeScript SDK. Python workers handle UMAP/HDBSCAN and RAGAS.

---

Project status

MVP1 (project CRUD, code/knowledge graphs, RAG, cost routing, read-only agents, MCP tools, vectors, evals, sandbox, skills autoresearch) plus the local-first post-MVP1 blocks (Hub, Cookbook, Observatory, panel extensions, security, quality loop, multi-IDE, richer MCP, agent catalog + permissions) are implemented. This is a solo-maintained FOSS project; expect rough edges and please open issues.

Intentionally out of scope for now: paid billing/Stripe, commercial multi-tenant, a paid marketplace, one-click cloud deploy, and a hosted cloud Hub (v1 is local-first).

---

Documentation

Full docs live in docs/ (English) and docs/es/ (Español):

• Getting started · Primeros pasos
• Architecture · Arquitectura
• Deployment
• Community: Contributing · Code of Conduct · Security

Contributing

Issues and PRs are welcome — see CONTRIBUTING.md (Español). Please keep changes surgical, add tests/evals for new behavior, and avoid introducing AGPL/GPL dependencies into the core. Run pnpm typecheck and pnpm test before opening a PR. By participating you agree to our Code of Conduct.

---

License

MIT © yaggo-brain contributors.

---

Acknowledgments

yaggo-brain stands on the shoulders of the open-source community. Grateful thanks to the following free/open-source projects (license in parentheses):

Core stack

• Next.js (MIT) and React Flow / xyflow (MIT)
• NestJS (MIT)
• Apache AGE (Apache-2.0) and pgvector (PostgreSQL License)
• Drizzle ORM (Apache-2.0)
• BullMQ (MIT) and Valkey (BSD-3-Clause)
• tree-sitter (MIT)
• LangGraph.js (MIT)
• LiteLLM (MIT) and Ollama (MIT)
• Better Auth (MIT)
• Docling (MIT)
• RAGAS (Apache-2.0) and Promptfoo (MIT)
• Langfuse (MIT)
• MCP TypeScript SDK (MIT)

Patterns & inspiration

• codebase-memory-mcp (MIT) — code-graph engine and the team-shared graph-artifact pattern
• Repomix (MIT) — AI-friendly repo packing
• superpowers (MIT) — agentic SDLC skills + multi-harness distribution
• ponytail (MIT) — minimalist senior-engineer style
• MarkItDown (MIT) — document → Markdown ingestion
• headroom (Apache-2.0) — context compression
• claude-mem (AGPL-3.0) — 3-layer retrieval, hooks & observation patterns (patterns only; not forked)

Also thanks to the Model Context Protocol community and the tree-sitter grammar authors. If your project should be listed here (or credited differently), please open an issue.