search

Semantic search across the knowledge graph. Uses vector similarity to find relevant entities based on meaning, not just keywords.

Synopsis

sibyl search <query> [options]

Arguments

Argument	Required	Description
query	Yes	Search query (natural language)

Options

Option	Short	Default	Description
--type	-t	(all)	Filter by entity type
--limit	-l	10	Maximum results to return
--all	-a	false	Search all projects (bypass context)
--json	-j	false	Output as JSON

Entity Types

Common types to filter by:

• task - Tasks in projects
• project - Projects
• epic - Feature groups
• pattern - Code patterns and best practices
• episode - Knowledge episodes
• error_pattern - Error patterns and solutions
• document - Crawled documents

Examples

Basic Search

sibyl search "authentication flow"

Output:

Found 5 results:

  JWT Authentication Pattern (pattern) 0.92
  Auth middleware implementation (episode) 0.87
  OAuth2 integration guide (document) 0.85
  Fix auth token refresh (task) 0.81
  Session management (pattern) 0.78

Filter by Type

Search only for tasks:

sibyl search "database migration" --type task

Search for patterns:

sibyl search "error handling" -t pattern

Increase Results

sibyl search "React hooks" --limit 20

Search All Projects

By default, search is scoped to the current project context. Use --all to search globally:

sibyl search "deployment" --all

JSON Output

For scripting and AI agents:

sibyl search "testing" --json

{
  "results": [
    {
      "id": "ent_abc123",
      "name": "Unit Testing Patterns",
      "type": "pattern",
      "score": 0.94,
      "description": "Best practices for unit testing React components..."
    },
    {
      "id": "task_xyz789",
      "name": "Add integration tests",
      "type": "task",
      "score": 0.87,
      "metadata": {
        "status": "todo",
        "priority": "high"
      }
    }
  ],
  "total": 2
}

Pipe to jq

Extract specific fields:

sibyl search "API" --json | jq -r '.results[] | "\(.name): \(.score)"'

Get the top result's ID:

sibyl search "auth" --json | jq -r '.results[0].id'

Search Quality Tips

Be Specific

# Better
sibyl search "JWT token refresh handling in Express middleware"

# Less effective
sibyl search "tokens"

Use Domain Terms

The search understands technical terminology:

sibyl search "React useEffect cleanup memory leak"
sibyl search "PostgreSQL connection pooling"
sibyl search "GraphQL N+1 query problem"

Combine with Type Filter

When looking for specific entity types:

# Find tasks about a topic
sibyl search "performance optimization" --type task

# Find patterns about a topic
sibyl search "caching strategies" --type pattern

Project Context

Search respects project context:

1. With linked directory: Searches only that project
2. With --context: Searches the specified project
3. With --all: Searches all projects

# Search in linked project
cd ~/dev/my-project
sibyl search "auth"

# Search in specific project
sibyl search "auth" --context proj_abc123

# Search everywhere
sibyl search "auth" --all

Related Commands

• sibyl add - Add new knowledge
• sibyl explore related - Find related entities
• sibyl entity show - View entity details