Sibyl is a Collective Intelligence Runtime - an MCP server providing AI agents shared memory, task orchestration, and collaborative knowledge through a Graphiti-powered knowledge graph.
See package READMEs for detailed documentation:
README.md— Project overview, quickstart, philosophyapps/api/README.md— Server daemon (sibyld), MCP API, REST endpointsapps/cli/README.md— Client CLI (sibyl), user commandsapps/web/README.md— Web UI, components, React Query hookspackages/python/sibyl-core/README.md— Core library, models, graph client
This project uses Sibyl as its own knowledge repository.
Use /sibyl for ALL Sibyl operations. This skill knows the correct patterns and handles
authentication properly.
/sibyl- Search, explore, add knowledge, manage tasks, project audits, sprint planning
Never call Sibyl MCP tools or CLI directly without going through a skill first.
Use /uv before running any uv commands. The skill provides current best practices and
prevents common mistakes.
- NEVER run
uv pip— it bypasses the project's dependency management. Useuv add,uv sync, oruv runinstead.
Every significant task follows this cycle:
1. RESEARCH (before coding)
/sibyl search "topic"
/sibyl explore patterns
2. DO (while coding)
/sibyl task start <id>
3. REFLECT (after completing)
/sibyl task complete <id> --learnings "What I learned"
/sibyl add "Pattern Title" "What, why, how, caveats"
sibyl/
├── apps/
│ ├── api/ # sibyld - Server daemon (serve, worker, db)
│ ├── cli/ # sibyl - Client CLI (task, search, add, etc.)
│ ├── runner/ # sibyl-runner - Distributed execution daemon
│ └── web/ # Next.js 16 frontend
├── packages/python/
│ └── sibyl-core/ # Shared library (models, graph, tools)
├── skills/ # Claude Code skills
└── charts/ # Helm charts
| Binary | Package | Purpose |
|---|---|---|
sibyld |
apps/api |
Server daemon (serve, worker, db, up/down) |
sibyl |
apps/cli |
Client CLI (task, search, add, explore) |
sibyl-runner |
apps/runner |
Distributed execution daemon |
⚡ Always use moon for monorepo operations. Moon handles task orchestration, caching, and
cross-package dependencies. Never use raw pnpm/uv commands for lint, test, build, or typecheck.
# Lifecycle
moon run dev # Start everything (FalkorDB, API, worker, web)
moon run stop # Stop all services
# Quality (from any directory)
moon run :lint # Lint current project (or all if at root)
moon run :test # Test current project
moon run :typecheck # Typecheck current project
moon run :check # All quality checks (lint + typecheck + test)
# Target specific packages
moon run web:lint # Lint web app
moon run api:test # Test API
moon run core:check # Full check on sibyl-core
# Build & Install
moon run :build # Build current project
moon run install-dev # Install everything editable (sibyl, sibyld, skills)
moon run install # Install everything (production)Why moon? Caches results, runs only what changed, handles dependencies between packages. A bare
pnpm lint won't respect the monorepo graph and may miss cross-package issues.
Use these when debugging Sibyl itself. Requires OWNER role.
# System health at a glance
sibyl debug status # API/worker/graph/queue health + recent errors
# Inspect the graph directly
sibyl debug schema # Entity types and counts
sibyl debug query "MATCH ..." # Run read-only Cypher queries
# Server logs
sibyl logs tail # Last 50 log entries
sibyl logs tail -n 100 # More entries
sibyl logs tail -l error # Filter by level (debug/info/warning/error)
sibyl logs tail -s api # Filter by service (api/worker)
sibyl logs tail -f # Stream in real-time (Ctrl+C to stop)
# JSON output for scripting
sibyl debug status --json
sibyl logs tail --jsonWhen to use:
- Tests failing mysteriously →
sibyl logs tail -l error - Graph queries returning unexpected results →
sibyl debug query "MATCH ..." - Need to understand entity distribution →
sibyl debug schema - Something feels broken →
sibyl debug status
| Service | Port |
|---|---|
| API + MCP | 3334 |
| Frontend | 3337 |
| FalkorDB | 6380 |
Every graph operation requires org context - NO defaults:
manager = EntityManager(client, group_id=str(org.id))Each organization gets its own isolated FalkorDB graph. Forgetting org scope queries the wrong graph or breaks isolation.
All writes use a semaphore to prevent corruption:
async with client.write_lock:
await client.execute_write_org(org_id, query, **params)Graphiti creates two node types:
Episodic- Created byadd_episode()Entity- Extracted entities
Queries must handle both:
WHERE (n:Episodic OR n:Entity) AND n.entity_type = $type# Core library
from sibyl_core.models import Task, Entity
from sibyl_core.graph import EntityManager
# Server-side (apps/api)
from sibyl.auth.context import get_current_user
from sibyl.cli.common import ELECTRIC_PURPLE- Port 6380 (not 6379) to avoid Redis conflicts
- Graph corruption can crash - nuke with
GRAPH.DELETE <org-uuid> - SEMAPHORE_LIMIT must be set before importing graphiti
add_episode()createsEpisodicnodes, notEntitynodes- Always query both labels
- Server components are default - add
'use client'only when needed - Middleware file is
proxy.ts(notmiddleware.ts) - API rewrites:
/api/*proxies to backend:3334
- Use
moon runfor everything — lint, test, build, typecheck. No exceptions. - Run
/uvskill first before any uv commands to get current best practices - NEVER use
uv pip— always useuv add,uv sync, oruv runinstead - Run from workspace root unless working on isolated package
uv syncat root syncs all Python deps- Raw
pnpm/uvcommands bypass moon's caching and dependency graph
When working on Sibyl itself:
- Run
/sibylat session start - Check current tasks:
sibyl task list --status doing - Start a task:
sibyl task start <id> - Search for context: Query Sibyl for relevant patterns
- Implement following patterns in the READMEs
- Complete with learnings:
sibyl task complete <id> --learnings "..." - Capture new knowledge: Add patterns for gotchas discovered
--sc-purple: #e135ff; /* Primary, importance */
--sc-cyan: #80ffea; /* Interactions */
--sc-coral: #ff6ac1; /* Secondary, data */
--sc-yellow: #f1fa8c; /* Warnings */
--sc-green: #50fa7b; /* Success */
--sc-red: #ff6363; /* Errors */See apps/web/README.md for full design system documentation.