trellis-kb

Trellis

A structured, queryable knowledge base focused on AI agents — concepts, frameworks, research, tools, workflows, people, papers. Stored as a graph, exposed over REST + MCP, with a Notion-shaped wiki UI and scriptable widgets.

The name: a trellis is a lattice structure that supports climbing plants. Same idea here — a scaffold on which knowledge grows and connects.

---

Screenshots

Home	Domain article (long-form, scrollable, sticky TOC)

Tools article	Single node (editor view)

Reading list (curated, cross-domain)	Reading list editor

Graph	All pages

Widgets index	Vega-Lite chart widget

---

What's in it

• Graph backend — PostgreSQL with pgvector (placeholder for future embeddings), tsvector full-text search, recursive-CTE graph traversal. No ORM.
• Workspaces — full isolation between workspaces; every node, edge, widget, comment, and version is scoped. No cross-workspace queries.
• REST API — every resource mounted under /api/v1/workspaces/:ws/….
• MCP server — Model Context Protocol over SSE at /mcp, so any MCP-aware agent (Claude Code, Claude Desktop, etc.) can read and write the graph.
• Script sandbox — POST /run executes JS in a vm sandbox with a workspace-scoped kb SDK injected, plus fetch for third-party APIs. Python supported via subprocess.
• Widgets — persistent, renderable outputs from agent scripts. Renderer + data are independent: vega-lite (charts), table, markdown (with templates), graph (arbitrary node/edge graphs), and html (sandboxed iframe escape hatch).
• Reading UI — Notion-shaped React SPA with two browse modes:
  • Domain articles — opening a domain shows every node concatenated as sections with a sticky TOC + scroll-spy + TOC fuzzy search. Sections below the fold lazy-render (placeholder until 500px from viewport), so a 200-node article still paints fast. Mermaid diagrams render on demand. In-article wikilinks scroll smoothly; cross-article wikilinks navigate.
  • Reading lists — curated, ordered selections that may span any domain. Each item has an optional editorial note that appears above the section body. Manage from the UI or from kb_list_* MCP tools, so an agent can build a "learning path" through the graph and refresh it later. Editing per node (CodeMirror with [[-autocomplete), threaded comments, version history with side-by-side diff, force-directed graph view.
• Versioning — every save snapshots into node_versions. Diff and restore from the UI.

---

Quick start

Option A — Docker only (recommended)

You need Docker with Compose.

git clone https://github.com/kaiohenrique/Trellis.git
cd Trellis
cp .env.example .env
docker compose up -d                     # start Postgres
docker run --rm --network host \
  --env-file .env \
  ghcr.io/kaiohenrique/trellis:latest \
  npm run seed -w server                  # seed the AI Agents workspace
docker run -d --name trellis --network host \
  --env-file .env \
  ghcr.io/kaiohenrique/trellis:latest

Open http://localhost:3000.

Option B — Source + Docker Postgres (for development)

You need Node 20+ and Docker.

git clone https://github.com/kaiohenrique/Trellis.git
cd Trellis
cp .env.example .env
docker compose up -d         # only postgres
npm install
npm run migrate              # create schema + ai-agents workspace
npm run seed                 # load 20 seed nodes + 5 widgets
npm run dev                  # api on :3000, vite on :5173

Open http://localhost:5173.

Option C — Fully manual

You need Node 20+ and a reachable PostgreSQL 14+ with the vector and pg_trgm extensions.