buddy — Agent-first Knowledge Graph

A graph-based knowledge substrate for LLMs and AI agents, with a human-readable dashboard.

buddy is an MCP server that provides 25 tools for managing a knowledge graph. Agents store concepts, facts, decisions, templates, and configs as Nodes, connected by typed Edges. Humans see everything through a server-rendered dashboard.

Features

• Unified Node Model — One entity type replaces 5 (knowledge, documents, memories, variables, skills)

• Knowledge Graph — Typed edges between nodes, projects, and tasks with a validation matrix

• 25 MCP Tools — CRUD, full-text search (FTS5), graph traversal, context loading

• Health Score — Per-project score (A-F) based on momentum, deadlines, freshness

• Dashboard — Node browser, graph visualization (D3.js), project hub, activity log

• OAuth 2.1 — PKCE enforced, compatible with Claude.ai, Gemini CLI, Mistral Le Chat

• Encryption — AES-256-GCM for secret nodes via HKDF key derivation

• Graph Integrity — Automatic validation, orphan detection, health score impact

• Token-optimized — context_load designed for minimal token usage (<800 tokens)

Related MCP server: kg-memory-mcp

Quick Start

# 1. Clone
git clone git@github.com:enki-run/buddy.git && cd buddy

# 2. Install + configure
npm install
cp wrangler.toml.example wrangler.toml

# 3. Create D1 database
wrangler d1 create buddy
# → Copy database_id into your wrangler.toml

# 4. Create KV namespace
wrangler kv namespace create CACHE
# → Copy id into your wrangler.toml

# 5. Run migrations
npm run migrate

# 6. Set token (min 32 hex chars)
openssl rand -hex 32
wrangler secret put BUDDY_TOKEN

# 7. Deploy
npm run deploy

See docs/installation.md for custom domain, rate limiting, and local development setup.

MCP Configuration

{
  "mcpServers": {
    "buddy": {
      "url": "https://buddy.yourdomain.com/mcp",
      "headers": { "Authorization": "Bearer <BUDDY_TOKEN>" }
    }
  }
}

OAuth 2.1 discovery: /.well-known/oauth-authorization-server

Tool Filtering

Limit exposed tools via ?tools= query parameter:

/mcp?tools=nodes       — Node + Edge tools only
/mcp?tools=tasks       — Task tools only
/mcp?tools=nodes,tasks — Combination
/mcp                   — All 25 tools

Node Types

All node types support an optional url field for linking to external resources (product pages, docs, RFCs, etc.). Nodes with URLs appear as clickable links in the project sidebar.

Edge Relations

Dashboard

System fonts (no external requests). Dark/light theme. Zoom S/M/L.

Documentation

• Installation Guide — Full setup including rate limiting

• Cloudflare API Token — Required permissions

• MCP Tools Reference — All 25 tools with examples

• Graph Integrity — Validation matrix, health score

• Token Rotation — BUDDY_TOKEN rotation, secret re-encryption

Tech Stack

• Runtime: Cloudflare Workers (V8 Isolates)

• Database: Cloudflare D1 (SQLite + FTS5)

• Cache: Cloudflare KV (60s TTL)

• Framework: Hono v4

• MCP: @modelcontextprotocol/sdk v1.27

MCP Provider Compatibility

buddy works natively with every major MCP-compatible AI provider:

buddy vs. Alternatives

Roadmap

buddy Team — Multi-user edition with shared knowledge graphs. Scopes (personal / team / org), role-based access (admin / member / reader), optimistic locking for concurrent edits. Single codebase with --mode=team flag.

buddy On-Prem — Docker self-hosted deployment for environments where data must not leave the network. SQLite-based, no cloud dependencies. Same MCP interface, same dashboard.

Signal Service — External ingest endpoint for GitHub webhooks, CI/CD events, and monitoring alerts. Separate microservice that feeds into buddy via MCP after LLM-based relevance filtering.

Contributing

See CONTRIBUTING.md for architecture, dev setup, and how to add tools or views.

Security

See SECURITY.md for reporting vulnerabilities.

License

Apache 2.0 — see LICENSE