One CLI. One graph. Every AI tool you use, sharing memory.
_{✦ Cross-agent memory for AI coding tools · self-hostable · yours to keep ✦}

Why Sibyl? • Quickstart • Memory Loop • CLI • Skills • MCP • 📖 Docs

---

🔮 Why Sibyl

In 2026, every app remembers you. Your assistant imports your history from the last one, every tool quietly assembles a profile, and the memory you generate becomes someone else's asset. The question stopped being whether it remembers and became who the memory works for.

Sibyl is cross-agent memory where the answer is you. One knowledge graph holds your decisions, your gotchas, and the conventions you actually follow. It is self-hosted on your own hardware and shared across every coding agent you run: Claude Code, Codex, Cursor, and the agents you build yourself. Tell one tool your context, and every tool keeps it. Nothing harvested into a vendor's profile, nothing trapped behind an export you can't take.

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. The depth lives in the CLI; MCP is there for the clients that prefer it.

Switch tools, swap models, walk to a new machine. The graph comes with you, because it was always yours.

✦ 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, skills, 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 docs, import sources (mailboxes, archives), and ingest agent transcripts 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

Dashboard	Projects
Knowledge Graph	Task Workflow

⚡ Quickstart

# Shell installer: puts sibyl on your PATH, starts the local stack, opens setup UI
curl -fsSL https://raw.githubusercontent.com/hyperb1iss/sibyl/main/install.sh | sh

# Or Homebrew
brew install hyperb1iss/tap/sibyl && sibyl up

Use --remote for a CLI-only install against a hosted server, or --daemon for the embedded daemon without the web UI. For containers, sibyl docker init && sibyl docker up brings up API, web, and SurrealDB. Full matrix in Installation.

First Five Minutes

# 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

# 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

🪄 The Memory Loop

Sibyl is built around a durable loop that both humans and agents follow:

recall ──▶ act ──▶ remember ──▶ reflect
   ▲                                │
   └────────────────────────────────┘

1. 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 project.
2. Act with that context in hand.
3. Remember durable knowledge as you learn it. sibyl remember stores decisions, plans, ideas, claims, procedures, and gotchas so the next session does not rediscover them.
4. Reflect at clean breakpoints. sibyl reflect distills 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 Capturing Knowledge.

The CLI

The CLI is the power-user interface: clean output, built for scripting and durable project workflows.

# 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 ingest claude-code ~/transcripts/   # Import agent transcripts into memory
sibyl docs list                           # Browse document collections
sibyl project link proj_xxx

Tasks flow backlog → todo → doing → review → done → archived (with a blocked side state), and every list command supports --json and --csv for scripting. 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.

🛠️ Skills & Hooks

Skills are how an agent learns to use Sibyl, the bridge that makes "if your agent can run a command, it speaks Sibyl" real. The loader teaches the memory loop, every CLI verb with the flags that actually exist on your machine, context-pack usage, and the error patterns to avoid, so agents stop guessing the interface from stale training data.

Skills are not Claude-only. sibyl skill install drops the loader into every agent skill root it knows: Claude Code (~/.claude/skills), Codex (~/.codex/skills), and the generic ~/.agents/skills convention. The same workflow follows you across tools.

sibyl skill install        # Install the tiny /sibyl loader into every agent skill root
sibyl skill list           # List the version-matched packs the CLI can serve
sibyl skill get core       # Print the full workflow + command contract
moon run hooks:install     # Optional Claude Code context hooks for repo dev

The installed skill is deliberately tiny: a loader that points the agent back at the CLI. The real skill packs (core, quick, workflows, examples, migration) are built into the CLI and served on demand with sibyl skill get, each matched to the exact Sibyl version on the machine. Upgrade the CLI and the guidance upgrades with it. No stale skill copies drift out of sync, and a subagent on any host gets the same source of truth from one command.

Hooks are separate and, for now, specific to Claude Code: a single SessionStart hook prints a compact wake-up bundle with active tasks and relevant memory, then the agent owns invoking the sibyl skill and calling sibyl recall for working context. See Skills & Hooks.

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"
      }
    }
  }
}

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)

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 in one runtime
• AI routing: Anthropic, OpenAI, and Gemini swap per surface; embeddings are pluggable
• Coordination: In-process by default; Redis/Valkey is optional for multi-process deployments
• Build: moonrepo + uv (Python) + pnpm (TypeScript)

See Why SurrealDB for the rationale and Storage Modes for the mode matrix.

🧪 Benchmarks

Sibyl reaches the LongMemEval-S retrieval ceiling on the live /api/search path, measured in an ephemeral CI stack, 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%

hit@5 and strict recall@5 measure different things, and many published "LongMemEval" numbers are end-to-end QA accuracy with an LLM judge, a different metric than retrieval recall. Full results and honest side-by-side positioning: LongMemEval · AI Memory Landscape.

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

Authentication supports JWT sessions for the web UI, scoped API keys for programmatic access (sibyl auth api-key create --scopes mcp,api:read), GitHub OAuth, and self-service password reset over SMTP. MCP endpoints enforce Bearer auth when a JWT secret is set. Detailed guides: Docker Compose · Kubernetes · Environment · Auth reference.

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

The full registry and how types relate live in Entity Types.

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 wants the memory they generate to stay theirs, across every tool.

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, so you own your data. It includes a full task workflow system, not just memory, 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, see the Benchmarks above.

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 from the web admin settings. A typical solo developer uses around $5/month in API costs.

Is it production-ready?

Yes. Sibyl is 1.0. SurrealDB is the runtime for graph, content, and auth. We use Sibyl to build Sibyl. Every feature, task, and learning you see here was tracked inside the system itself.

🎯 What's Next

Past 1.0, the work is making memory more automatic and the sources deeper:

• Memory Workspace OS: automatic memory decisions become visible, explainable, correctable, and undoable from one product surface.
• Correction propagation: edits, redactions, and rollbacks flow forward into future recall and synthesis, not just the record you touched.
• Broader ingestion: source import reaches past mailbox-style archives into more corpora, scoped and provenance-tracked.

Already shipped on the way here: a Surreal-only default runtime, plus source, document, and agent transcript ingestion via sibyl ingest and sibyl docs. See docs/architecture/SIBYL_1_0_ROADMAP.md for the full direction.

💜 Philosophy

Recall before you act. The graph knows things, so pull context before you code. Work in task context for traceability, progress, and knowledge linking. Remember what you learn: if it took time to figure out, save it so the next session doesn't pay for it twice.

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

The graph should be smarter after every session.

Contributing

We welcome contributions. See CONTRIBUTING.md for guidelines.

# One-line setup (installs proto, moon, toolchain, dependencies)
./setup-dev.sh              # macOS / Linux
pwsh -File .\setup-dev.ps1  # Windows (PowerShell 7+)

# Configure your shell, then launch the local-dev stack
export SIBYL_OPENAI_API_KEY=sk-...   # embeddings; SIBYL_JWT_SECRET auto-generates in dev
moon run install-dev                 # editable CLI installs
moon run dev                         # SurrealDB + API + web

# Verify, then run the quality gates before a PR
curl http://localhost:3334/api/health
moon run :check                      # lint + typecheck + test

moon run dev is the single-machine flow: with SIBYL_SURREAL_URL unset it starts local SurrealDB, points the API at ws://127.0.0.1:8000/rpc, and stores data in .moon/cache/surreal-dev. Set SIBYL_SURREAL_URL to use a hosted endpoint, including Surreal Cloud.

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

License

Apache-2.0. See LICENSE.

---

  

<sub>If Sibyl helps your team remember, give us a star or support the project

✦ Built with obsession by Hyperbliss Technologies ✦</sub>