sibyl
hyperb1iss/sibyl
Collective intelligence runtime for AI agents. Knowledge graph + persistent memory.
Instalação
npx convez-ai hyperb1iss/sibyl1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
🔮 Why Sibyl
Sibyl is cross-agent memory for AI coding tools: one self-hostable knowledge graph shared across Claude Code, Codex, OpenCode, Cursor, and the agents you build yourself. Tell one tool your context, and every tool keeps it.
Most AI sessions start cold. Coding agents forget yesterday's decisions. Notes drift between worktrees, tasks scatter across tools, and the context you earned the hard way evaporates the moment a session ends.
The interaction surface is the shell. If your agent can run a command, it already speaks Sibyl. No SDK to adopt, no MCP server you are locked into. Claude Code, Codex, Cursor, Aider, Cline, and your own scripts all recall context, capture learnings, and run task workflows the same way you do. MCP is there for the clients that prefer it; the depth lives in the CLI.
A durable knowledge graph holds what matters: personal context, project work, shared spaces, source
documents, decisions, agent state. Each lives in its own scope and gets tied to the others when
context calls for it. A built-in memory loop (recall → act → remember → reflect) keeps hard-won
context close at hand for humans and AI alike. Source-grounded synthesis turns what you already know
into verified documents.
Every session adds up instead of starting over.
✦ What You Get
| Capability | What It Means |
|---|---|
| 🔮 Compounding Context | Every session adds to the graph instead of starting over. The longer you use it, the sharper it gets |
| 🪄 The Memory Loop | recall → act → remember → reflect runs through the CLI, MCP, and hooks. Agents wake with context and leave it behind |
| 🎯 Semantic Search | Find knowledge by meaning. "Authentication patterns" surfaces OAuth notes even when "OAuth" isn't in the text |
| 🦋 Task Workflow | Plan with epics and tasks, then track execution across sessions and teammates in one place |
| 🧪 Source-Grounded Synthesis | Draft verified documents from your own memory with citation, freshness, and gap checks |
| 🌊 Source Ingestion | Crawl documentation sites and import sources (mailboxes, archives) into scoped raw content and graph memory |
| 💎 Scoped Multi-Tenancy | Namespace-isolated graphs, org-scoped content/auth records, and policy gates for personal, project, and team scopes |
⚡ Quickstart
Shell Installer
curl -fsSL https://raw.githubusercontent.com/hyperb1iss/sibyl/main/install.sh | sh
The installer puts sibyl on your PATH, starts the local API + web stack, and opens the setup UI
when it is ready. Use --remote for CLI-only installs and --daemon for the embedded daemon
without the web UI.
Homebrew
brew install hyperb1iss/tap/sibyl
sibyl up
Remote CLI
curl -fsSL https://raw.githubusercontent.com/hyperb1iss/sibyl/main/install.sh | sh -s -- --remote
sibyl init --remote https://sibyl.example.com
sibyl auth login
Docker Self-Host
sibyl docker init # Generate ~/.sibyl/docker/.env + compose
sibyl docker up # Start API, web, and SurrealDB
sibyl docker logs # Follow logs
sibyl docker down # Stop services
sibyl docker upgrade # Pull and recreate
First Five Minutes
Everything below runs against your local Sibyl stack. MCP wiring is optional.
# Capture a learning the moment you find it
sibyl remember "Stale auth token bug" \
"Redis TTL mismatch dropped the cached token early" --kind error_pattern
# Pull it back as working context for your next session
sibyl recall "auth token bug" --intent debug
# Or search semantically across the whole graph
sibyl search "stale auth token redis ttl"
# Package wake-up context for the next coding session
sibyl session bundle
Development Setup
# One-line setup (installs proto, moon, toolchain, dependencies)
./setup-dev.sh # macOS / Linux
pwsh -File .\setup-dev.ps1 # Windows (PowerShell 7+)
# Or manually:
curl -fsSL https://moonrepo.dev/install/proto.sh | bash
proto use # Installs node, pnpm, python, uv
proto install moon
uv sync && pnpm install
# Configure your shell
export SIBYL_OPENAI_API_KEY=sk-...
# SIBYL_JWT_SECRET is auto-generated in dev.
# Embeddings use SIBYL_OPENAI_API_KEY or SIBYL_GEMINI_API_KEY.
# Install CLIs globally (editable, source changes reflect immediately)
moon run install-dev
# Launch the default local-dev stack (SurrealDB + API + web)
moon run dev
# Verify
curl http://localhost:3334/api/health
moon run dev is the single-machine flow. When SIBYL_SURREAL_URL is unset it starts local
SurrealDB, points the API at ws://127.0.0.1:8000/rpc, and stores data files in
.moon/cache/surreal-dev. Jobs and schedules run in-process by default
(SIBYL_COORDINATION_BACKEND=local). Set SIBYL_SURREAL_URL to connect to a hosted SurrealDB
endpoint, including Surreal Cloud, instead.
Ports:
| Service | Port | URL |
|---|---|---|
| API + MCP | 3334 | http://localhost:3334 |
| Web UI | 3337 | http://localhost:3337 |
| SurrealDB | 8000 | ws://localhost:8000/rpc |
| Redis/Valkey | 6381 | optional |
🪄 The Memory Loop
Sibyl is built around a durable loop that both humans and agents follow:
recall ──▶ act ──▶ remember ──▶ reflect
▲ │
└────────────────────────────────┘
- Recall working context before you start.
sibyl recall "<goal>"returns a compact context pack: active work, decisions, plans, constraints, and recent lessons, scoped to your linked project. - Act with that context in hand.
- Remember durable knowledge as you learn it.
sibyl rememberstores decisions, plans, ideas, claims, procedures, and gotchas so the next session does not rediscover them. - Reflect at clean breakpoints.
sibyl reflectdistills raw session notes into reviewable memory candidates and can persist them into the graph.
sibyl recall "ship the context graph" --intent build
sibyl remember "Use context packs" "Group memory before dispatching agents" --kind decision
sibyl reflect "We decided X. Next we build Y." --title "Planning checkpoint" --persist
Memory is graded, auditable, and scoped. Raw captures stay verbatim, reflection candidates pass an
automatic review before promotion, and a nightly dream-cycle keeps the graph consolidated. See
docs/guide/capturing-knowledge.md.
The CLI
The CLI is the power-user interface. Clean output, built for scripting and durable project workflows.
curl -fsSL https://raw.githubusercontent.com/hyperb1iss/sibyl/main/install.sh | sh
moon run cli:install # or install from source
Command Families
# Memory loop
sibyl recall "<goal>" # Compile working context
sibyl remember "Title" "Body" # Store durable memory
sibyl reflect "<notes>" --persist # Distill notes into candidates
sibyl capture "<quick note>" # Fast verbatim capture
sibyl search "authentication patterns"
# Knowledge & graph
sibyl add "Redis pooling" "Pool size must be >= concurrent requests"
sibyl explore related ent_xyz # Find connected entities
sibyl show <id> # Full content by ID
# Task workflow
sibyl task list --status todo,doing
sibyl task start <task_id>
sibyl task complete <task_id> --learnings "Key insight: check TTL first"
# Synthesis, sources, projects, orgs
sibyl synthesis draft "Onboarding guide"
sibyl crawl add "https://docs.example.com" --name "Example Docs"
sibyl project link proj_xxx
Task Workflow
backlog ──▶ todo ──▶ doing ──▶ review ──▶ done ──▶ archived
│
▼
blocked
Output Formats
sibyl task list # Table output (default)
sibyl task list --json # JSON for scripts
sibyl task list --csv # For spreadsheets
Full command reference: docs/cli/.
🦋 Web UI
A full admin interface at http://localhost:3337:
- Dashboard: Stats overview, recent activity, quick actions
- Tasks: Kanban-style workflow with inline editing
- Graph: Interactive force-directed visualization of knowledge connections
- Search: Semantic search with filters
- Memory: The memory workspace, raw captures, source imports, and synthesis
- Sources: Configure and inspect documentation crawling
- Settings: Organizations, teams, API keys, security, LLM routing, backups
Built with: Next.js 16, React 19, React Query, Tailwind CSS 4, and the SilkCircuit design system.
MCP Integration
Connect Claude Code, Cursor, or any MCP client to Sibyl:
{
"mcpServers": {
"sibyl": {
"type": "http",
"url": "http://localhost:3334/mcp",
"headers": {
"Authorization": "Bearer sk_your_api_key"
}
}
}
}
The Tool API
Sibyl exposes eleven MCP tools, organized by what they do:
| Tool | Purpose |
|---|---|
search | Unified semantic search across graph and crawled docs |
context | Compile an agent context pack for a goal (intent + depth) |
explore | Navigate the graph: list, related, traverse, dependencies |
add | Create knowledge: episodes, patterns, tasks, projects |
remember | Capture durable memory: decisions, plans, ideas, claims |
reflect | Distill raw notes into reviewable memory candidates |
synthesis_plan | Plan source-grounded synthesis from authorized memory |
synthesis_draft | Draft, verify, and optionally remember an artifact |
synthesis_verify | Verify citation, freshness, and gap coverage |
manage | State changes: task lifecycle, crawling, analysis, admin |
logs | Recent server logs (requires OWNER role) |
Claude Code Skills & Hooks
Sibyl ships with skills and hooks for built-in Claude Code integration.
sibyl skill install # Install the tiny /sibyl loader skill
sibyl skill get core # Print version-matched guidance from the CLI bundle
moon run hooks:install # Optional Claude Code context hooks for repo dev
The installed /sibyl skill is intentionally tiny. It points agents back to the installed CLI,
which serves the full markdown skill packs for the exact Sibyl version on the machine. A single hook
nudges the agent at session boundaries; everything else is the agent's job:
| Hook | Trigger | Action |
|---|---|---|
| SessionStart | Session begins | Prints a compact session bundle with active tasks and relevant memory |
The agent is responsible for invoking the sibyl skill and calling sibyl recall /
sibyl context pack for working memory. We previously shipped a per-prompt context-injection hook
(UserPromptSubmit) but removed it: it substituted for skill invocation instead of prompting it,
and agents stopped reaching for the CLI.
See skills/ and hooks/ for implementation details.
Architecture
sibyl/
├── apps/
│ ├── api/ # sibyld - FastAPI + MCP server daemon
│ ├── cli/ # sibyl - REST client CLI
│ ├── web/ # Next.js 16 frontend
│ └── e2e/ # End-to-end tests
├── packages/python/
│ └── sibyl-core/ # Shared library (models, graph, ai, retrieval, services)
├── skills/ # Claude Code skills
├── hooks/ # Claude Code context hooks
├── charts/ # Helm chart for Kubernetes
├── infra/ # Ansible self-host + local compose
└── docs/ # Documentation site (VitePress)
Stack:
- Backend: Python 3.13 / FastAPI / FastMCP / SurrealDB-native runtime
- Frontend: Next.js 16 / React 19 / React Query / Tailwind 4
- Storage: SurrealDB unifies graph, content, and auth. PostgreSQL is retained only for migration and archive rehearsal.
- AI routing: Anthropic, OpenAI, and Gemini swap per surface; embeddings are pluggable.
- Coordination: In-process by default; Redis/Valkey is optional for multi-process or distributed deployments.
- Build: moonrepo + uv (Python) + pnpm (TypeScript)
- Compatibility: Legacy Graphiti-shaped records are handled by Sibyl-owned Surreal projection and archive code. No supported install pulls Graphiti.
See docs/guide/why-surreal.md for the rationale and
docs/guide/storage-modes.md for the mode matrix.
🧪 Benchmarks
Sibyl reaches the LongMemEval-S retrieval ceiling on the live API path with no LLM extraction and no LLM reranking.
| Metric | Value |
|---|---|
hit@5 | 100.00% (500/500) |
recall@5 | 96.96% (strict multi-answer) |
recall@10 | 98.90% |
ndcg@5 | 94.63% |
| Questions | 500/500 |
| LLM extraction | disabled |
| LLM reranking | none |
| Embeddings | OpenAI text-embedding-3-small, 1024 dims |
| Tenant isolation | graph namespace + scoped content per question |
The result is measured against the production /api/search surface in an ephemeral CI stack, not an
offline notebook replay. Each question gets an isolated graph namespace with scoped content rows,
and the full artifact and diagnostics are published.
hit@5 = 100% and strict recall@5 = 96.96% measure different things and we report both: hit asks
"did any correct session land in the top 5", strict recall asks "did every correct session land
for multi-answer questions". Many LongMemEval-S questions have multiple correct answer sessions,
which is why these numbers diverge.
A few comparisons that are not apples-to-apples are usually shown side by side in this space — retrieval recall vs LLM-judged QA accuracy is the most common conflation. See AI Memory Landscape for the honest field positioning.
- Headline run: GitHub Actions run 26304777971
- Full results doc:
docs/testing/longmemeval.md - Methodology:
docs/testing/benchmark-methodology.md - Architecture:
docs/architecture/retrieval-system.md
Authentication
JWT Sessions (Web UI)
SIBYL_JWT_SECRET=your-secret-key # Required in production; dev auto-generates
SIBYL_ACCESS_TOKEN_EXPIRE_MINUTES=60 # Optional (default: 60)
API Keys (Programmatic Access)
sibyl auth api-key create --name "CI/CD" --scopes mcp,api:read
# Scopes: mcp, api:read, api:write
OAuth (GitHub)
SIBYL_GITHUB_CLIENT_ID=...
SIBYL_GITHUB_CLIENT_SECRET=...
MCP endpoints enforce Bearer auth when a JWT secret is set (SIBYL_MCP_AUTH_MODE=auto). See
docs/api/ for the full auth reference.
Deployment
Docker Compose
sibyl docker init
sibyl docker up
Kubernetes (Helm)
helm install sibyl ./charts/sibyl \
--set backend.existingSecret=sibyl-secrets \
--set backend.surreal.existingSecret=sibyl-surreal \
--set ingress.enabled=true
See docs/deployment/ for detailed guides:
Knowledge Model
Sibyl models a wide range of entity types so memory stays structured, not just a pile of notes:
- Work:
task,epic,project,milestone - Knowledge:
pattern,episode,procedure,rule,guide,error_pattern - Memory:
decision,plan,idea,claim,artifact,session,note - Sources:
source,document,domain,community
The full registry and how types relate is documented in
docs/guide/entity-types.md.
FAQ
Who is Sibyl for?
Solo developers who want durable memory for projects and debugging. Teams who want shared knowledge that compounds. Anyone building with AI who is tired of repeating context every session.
Do I need AI agents to use Sibyl?
No. The knowledge graph and task system are the core product: documentation, task tracking, captured learnings, and semantic search over what your team already knows. AI agents make the memory loop automatic, but they are not required.
How does it compare to Mem0 / LangMem / similar?
Sibyl is self-hosted and open source. You own your data. It includes a full task workflow system, not just memory. It has a web UI for humans, not just APIs for machines. And it keeps knowledge, tasks, and docs connected in one graph instead of scattering them across tools.
On retrieval quality: Sibyl reaches the LongMemEval-S retrieval ceiling (500/500 hit@5, 96.96%
strict recall@5, 98.90% recall@10) on the live API path with no LLM extraction or LLM reranking.
Many published "LongMemEval" numbers are end-to-end QA accuracy with an LLM judge, which is a
different metric than retrieval recall — see
docs/testing/ai-memory-landscape.md for honest side-by-side
positioning.
What LLM APIs do I need?
- Anthropic, OpenAI, or Gemini (required): for language-model surfaces such as crawler extraction, synthesis, and reflection.
- OpenAI or Gemini (required): for embeddings and semantic search.
Providers and models are configurable globally or per surface, and the web admin settings page can save instance-wide model routing. A typical solo developer uses around $5/month in API costs.
Is it production-ready?
Sibyl is in active development (v0.10.x, heading toward 1.0). SurrealDB is the default runtime for graph, content, and auth; legacy PostgreSQL paths are retained only for migration and archive rehearsal. We use Sibyl to build Sibyl. Every feature, task, and learning you see here was tracked inside the system itself.
🎯 Roadmap
Where we're headed after v0.10.0, toward 1.0:
- Corpus Runtime: real private source corpora can be imported, searched, inspected, corrected, and synthesized without leaking scope.
- Memory Workspace OS: automatic memory decisions become visible, explainable, correctable, and undoable from one product surface.
- Surreal-only closure: remaining legacy assumptions leave the supported runtime once native behavior has receipts.
- 1.0 evidence freeze: release claims cite gates, artifacts, and install rehearsals.
The graph gets smarter. The workflow gets sharper. See
docs/architecture/SIBYL_1_0_ROADMAP.md.
💜 Philosophy
Recall Before You Act
The graph knows things. Before you code, pull context:
sibyl recall "what you're building" --intent build
sibyl search "error you hit" --type episode
Work In Task Context
Never do significant work outside a task. Tasks provide traceability, progress tracking, and knowledge linking.
Remember What You Learn
If it took time to figure out, save it:
sibyl remember "Descriptive title" "What, why, how, caveats" --kind decision
Bad: "Fixed the bug." Good: "JWT refresh fails when Redis TTL expires. Root cause: token service does not handle WRONGTYPE. Fix: try/except with regeneration fallback."
Complete With Learnings
sibyl task complete <id> --learnings "Key insight: ..."
The graph should be smarter after every session.
Contributing
We welcome contributions. See CONTRIBUTING.md for guidelines.
# Fork, clone, then:
./setup-dev.sh # macOS / Linux
pwsh -File .\setup-dev.ps1 # Windows (PowerShell 7+)
moon run dev
# Make changes, then:
moon run :check # Lint + typecheck + test
License
Apache-2.0. See LICENSE.