Agents & MCP

Sibyl runs as an MCP (Model Context Protocol) server, so any MCP-capable AI agent can use it as persistent memory. This guide explains how to connect an agent and what Sibyl exposes once it is wired in. It works the same for coding agents like Claude Code, Codex, and opencode, and for personal assistants like OpenClaw.

The CLI is the default agent interface. Most agents use Sibyl by running sibyl shell

commands (taught by the sibyl skill), which is lighter-weight than MCP and needs no per-client config. sibyl setup <url> signs the CLI in and installs the skill and the Claude Code hook in one step, or an agent can do it by following the sentence on the web app's Connect card (details). Reach for the MCP tools below when a client works better with structured tool calls. See Working with Agents. :::

What is MCP?

The Model Context Protocol (MCP) is an open standard that lets AI agents interact with external tools and data sources. Sibyl exposes 13 MCP tools:

Tool	Purpose
`search`	Unified semantic search across the graph and crawled docs
`context`	Compile a working context pack (intent, wake/recall/deep)
`synthesis_plan`	Plan source-grounded synthesis from authorized memory
`synthesis_draft`	Draft, verify, and optionally remember a synthesis artifact
`synthesis_verify`	Verify citation, freshness, redaction, and gap coverage
`explore`	Navigate the graph: list, related, traverse, dependencies
`expand_neighbors`	Widen known memories into their bounded neighborhood
`fetch_slice`	Read one memory at span granularity, citing its parent
`add`	Create knowledge entries (episodes, patterns, tasks, projects)
`remember`	Capture durable memory (decision, plan, idea, claim, ...)
`reflect`	Reflect raw notes into reviewable memory candidates
`manage`	State changes: task workflow, crawl, sync, analysis, admin
`logs`	Recent server logs (OWNER role)

The four memory-loop tools (context, remember, reflect, and the synthesis_* family) implement the memory loop for agents. search, explore, add, and manage cover retrieval and workflow. expand_neighbors and fetch_slice are the bounded traversal verbs for an agent that wants to steer its own retrieval over at most three rounds; see the traversal verbs for the contract they answer to.

Connecting an Agent

HTTP Mode (Recommended)

Point your agent at a running Sibyl server. The exact step depends on the client:

bash

# Claude Code
claude mcp add sibyl --transport http http://localhost:3334/mcp

# Codex
codex mcp add sibyl --url http://localhost:3334/mcp

Clients that use a JSON config file take the standard MCP server block:

json

{
  "mcpServers": {
    "sibyl": {
      "type": "http",
      "url": "http://localhost:3334/mcp"
    }
  }
}

On a remote server, swap in its URL for http://localhost:3334. See MCP Configuration for transport, auth, and per-client detail.

Subprocess Mode

Run Sibyl as a subprocess:

json

{
  "mcpServers": {
    "sibyl": {
      "command": "uv",
      "args": ["--directory", "/path/to/sibyl/apps/api", "run", "sibyld", "serve", "-t", "stdio"],
      "env": {
        "SIBYL_OPENAI_API_KEY": "sk-...",
        "SIBYL_JWT_SECRET": "your-secret"
      }
    }
  }
}

Use subprocess mode when:

Running locally without a server
Each project needs isolated state
CI/CD environments

Authentication

With Authentication

When SIBYL_JWT_SECRET is set, MCP requires authentication:

json

{
  "mcpServers": {
    "sibyl": {
      "type": "http",
      "url": "http://localhost:3334/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Create an API key:

bash

sibyl auth api-key create --name "my-agent" --scopes mcp

Without Authentication (Dev Mode)

Disable auth for local development:

bash

SIBYL_MCP_AUTH_MODE=off

Production Use Always enable authentication in production environments. :::

The Agent Workflow

The Memory Loop

1. RECALL           -> Pull working context with `context`
2. ACT              -> Start a task, do the work
3. REMEMBER         -> Capture decisions and learnings
4. REFLECT          -> Distill session notes into candidates

See The Memory Loop for the cycle in full.

Before Implementing

python

# Recall a working context pack for the goal, scoped to one project
context(goal="implement OAuth refresh", intent="build", project="proj_abc")

# Reading every project you can access is a deliberate choice
context(goal="find prior art for OAuth refresh", all_projects=True)

# Or search directly for relevant patterns
search("what you're building")
search("error handling patterns", types=["pattern"])

During Implementation

python

# Check for related work
explore(mode="list", types=["task"], project="proj_abc", status="doing")

# Track progress on the task description
manage("update_task", entity_id="task_xyz",
       data={"description": "Implemented OAuth callback"})
# For a timestamped note, use the CLI: sibyl task note task_xyz "..."

After Completing

python

# Complete with learnings
manage("complete_task", entity_id="task_xyz",
       data={"learnings": "OAuth redirect URIs must match exactly..."})

# Or add standalone knowledge
add("OAuth redirect insight",
    "Redirect URIs must match exactly including trailing slashes...",
    category="authentication")

Search returns previews; fetch the full record with sibyl show <id>. To seed memory with what your agents already learned, import their memory files with sibyl ingest memories, or import whole transcripts with sibyl ingest claude-code <path> or sibyl ingest codex <path>.

Tool Reference

search

Find entities by semantic meaning:

python

search(
    query="OAuth implementation patterns",
    types=["pattern", "episode"],    # Filter by type
    language="python",               # Filter by language
    status="todo",                   # Filter tasks by status
    project="proj_abc",              # Scope to project
    limit=10                         # Max results
)

context

Compile a working context pack for a goal. This is the recall step of the memory loop:

python

context(
    goal="implement OAuth refresh",
    intent="build",       # build, plan, review, debug, general
    layer="recall",       # wake (fast), recall (default), deep_search (wide)
    project="proj_abc"    # Scope recall to a project
)

remember

Capture durable, typed memory:

python

remember(
    title="Chose SurrealDB for the runtime",
    content="One engine replaces three backends...",
    kind="decision"       # decision, plan, idea, claim, episode, session, ...
)

reflect

Distill raw notes into reviewable memory candidates:

python

reflect(
    content="Long session notes to distill...",
    persist=True,         # Persist candidates into the graph
    review=True           # Route to the review queue instead of direct promotion
)

explore

Navigate the graph structure:

python

# List entities
explore(mode="list", types=["project"])
explore(mode="list", types=["task"], project="proj_abc", status="todo")

# Find related entities
explore(mode="related", entity_id="pattern_abc")

# Task dependencies
explore(mode="dependencies", entity_id="task_xyz")

# Multi-hop traversal
explore(mode="traverse", entity_id="proj_abc", depth=2)

add

Create new knowledge:

python

# Add a learning (default type: episode)
add(
    title="Redis connection insight",
    content="Pool size must be >= concurrent requests...",
    category="database",
    languages=["python", "redis"]
)

# Create a task
add(
    title="Implement OAuth",
    content="Add OAuth2 login flow",
    entity_type="task",
    project="proj_abc",
    priority="high"
)

# Create a pattern
add(
    title="Retry with backoff",
    content="Implementation pattern...",
    entity_type="pattern",
    languages=["python"]
)

manage

Handle state changes:

python

# Task workflow
manage("start_task", entity_id="task_xyz")
manage("complete_task", entity_id="task_xyz", data={"learnings": "..."})
manage("block_task", entity_id="task_xyz", data={"reason": "..."})

# Admin
manage("health")
manage("stats")

# Crawling
manage("crawl", data={"url": "https://docs.example.com", "depth": 3})

synthesis_plan / synthesis_draft / synthesis_verify

Draft verified documents grounded in your own memory:

python

# Plan a section outline from authorized memory
synthesis_plan(goal="How our auth system handles token refresh")

# Draft and verify an artifact
synthesis_draft(goal="Release runbook for sibyld")

# Verify citation, freshness, redaction, and gap coverage
synthesis_verify(goal="How our auth system handles token refresh")

See Synthesis for the three-stage flow in detail.

Skills Integration

What are Skills?

Skills are a knowledge-injection mechanism in agents like Claude Code and Codex. Sibyl ships a skill that teaches the agent how to use the knowledge graph effectively.

Installing Skills

sibyl setup installs the skill into Claude Code, Codex, and the generic ~/.agents/skills root, and registers the Claude Code SessionStart hook, as part of connecting a machine. To install only the skill, run sibyl skill install.

Using Skills

In a client that supports skills, invoke it as a slash command:

/sibyl

The skill teaches the agent:

CLI commands
Workflow patterns
Best practices
Common pitfalls

Skill Files

The repo keeps the installed loader in skills/:

skills/
└── sibyl/
    └── SKILL.md

The full /sibyl guidance stays in bundled CLI markdown packs. Use sibyl skill get core to print the version matched contract that the loader points agents toward.

Agent Patterns

Starting a Session

python

# 1. Check current context
explore(mode="list", types=["project"])

# 2. Find in-progress work
search("", types=["task"], status="doing")

# 3. Or find next todo
search("", types=["task"], status="todo", project="proj_abc")

# 4. Start working
manage("start_task", entity_id="task_xyz")

Research Pattern

python

# Before implementing, search for:
# 1. Existing patterns
search("what you're building", types=["pattern"])

# 2. Past learnings
search("related topic", types=["episode"])

# 3. Known issues
search("common mistakes with X")

# 4. Team rules
explore(mode="list", types=["rule"])

Knowledge Capture Pattern

python

# When you discover something non-obvious
add(
    title="Descriptive title",
    content="What, why, how, caveats...",
    category="domain",
    languages=["relevant", "languages"]
)

Task Completion Pattern

python

# Always complete with learnings
manage(
    action="complete_task",
    entity_id="task_xyz",
    data={
        "learnings": """
        Key insight: OAuth redirect URIs must match exactly.

        Problem: Google OAuth was silently failing
        Cause: Trailing slash mismatch in redirect URI
        Fix: Ensure production and config URIs match exactly
        """
    }
)

Best Practices

1. Search Before Implementing

Always check if relevant knowledge exists:

python

search("what you're about to build")

2. Work in Task Context

Don't do significant work without a task:

python

# Find or create a task first
explore(mode="list", types=["task"], project="proj_abc", status="todo")
manage("start_task", entity_id="task_xyz")

3. Capture Non-Obvious Learnings

If it took time to figure out, save it:

python

add("Descriptive title", "Detailed content with why and how")

4. Use Project Context

Scope task operations to projects:

python

explore(mode="list", types=["task"], project="proj_abc", status="todo")

5. Complete with Learnings

The learnings field is where value accumulates:

python

manage("complete_task", entity_id="task_xyz",
       data={"learnings": "Specific, actionable insight"})

Troubleshooting

Connection Failed

Check server is running: curl http://localhost:3334/api/health
Verify URL in MCP config
Check firewall/network settings

Authentication Errors

Verify API key is valid
Check key has mcp scope
Ensure Authorization header is set

No Results from Search

Check organization context
Verify entity types exist
Try broader search terms

Tools Not Available

Restart your agent
Check MCP server logs
Verify config syntax

Example Session

A complete session might look like:

python

# 1. Start session - check context
explore(mode="list", types=["project"])
# Returns: proj_auth, proj_api, proj_web

# 2. Find my in-progress work
search("", types=["task"], status="doing", project="proj_auth")
# Returns: task_oauth (OAuth implementation)

# 3. Search for relevant patterns
search("OAuth callback handling", types=["pattern"])
# Returns: pattern_oauth_callback

# 4. Work on implementation...

# 5. Capture a discovery
add(
    title="OAuth state parameter must be cryptographic",
    content="Using predictable state parameters enables CSRF attacks...",
    category="security",
    languages=["python"]
)

# 6. Complete task
manage("complete_task", entity_id="task_oauth",
       data={"learnings": "OAuth state must be cryptographic random..."})

Next Steps

The Memory Loop - The cycle agents follow
Skills Development - Create custom skills
MCP Configuration - Advanced configuration
Agent Collaboration - Shared-assistant patterns

Agents & MCP ​

What is MCP? ​

Connecting an Agent ​

HTTP Mode (Recommended) ​

Subprocess Mode ​

Authentication ​

With Authentication ​

Without Authentication (Dev Mode) ​

The Agent Workflow ​

The Memory Loop ​

Before Implementing ​

During Implementation ​

After Completing ​

Tool Reference ​

search ​

context ​

remember ​

reflect ​

explore ​

add ​

manage ​

synthesis_plan / synthesis_draft / synthesis_verify ​

Skills Integration ​

What are Skills? ​

Installing Skills ​

Using Skills ​

Skill Files ​

Agent Patterns ​

Starting a Session ​

Research Pattern ​

Knowledge Capture Pattern ​

Task Completion Pattern ​

Best Practices ​

1. Search Before Implementing ​

2. Work in Task Context ​

3. Capture Non-Obvious Learnings ​

4. Use Project Context ​

5. Complete with Learnings ​

Troubleshooting ​

Connection Failed ​

Authentication Errors ​

No Results from Search ​

Tools Not Available ​

Example Session ​

Next Steps ​

Agents & MCP

What is MCP?

Connecting an Agent

HTTP Mode (Recommended)

Subprocess Mode

Authentication

With Authentication

Without Authentication (Dev Mode)

The Agent Workflow

The Memory Loop

Before Implementing

During Implementation

After Completing

Tool Reference

search

context

remember

reflect

explore

add

manage

synthesis_plan / synthesis_draft / synthesis_verify

Skills Integration

What are Skills?

Installing Skills

Using Skills

Skill Files

Agent Patterns

Starting a Session

Research Pattern

Knowledge Capture Pattern

Task Completion Pattern

Best Practices

1. Search Before Implementing

2. Work in Task Context

3. Capture Non-Obvious Learnings

4. Use Project Context

5. Complete with Learnings

Troubleshooting

Connection Failed

Authentication Errors

No Results from Search

Tools Not Available

Example Session

Next Steps