v0.3.0

Release Notes v0.3.0

Released: 2026-02-07

This release delivers major improvements to agent orchestration, graph performance, and web UI. The focus is on eliminating architectural complexity, boosting search speed, and providing better visibility into agent operations through a redesigned command center.

Highlights

Simplified Agent Architecture

Removed the over-engineered three-tier orchestration system (MetaOrchestrator → TaskOrchestrator → Worker) in favor of direct agent spawning with parent-child relationships. Agents now self-manage through parent_agent_id links, budget limits, and trajectory capture. The AgentRecord model preserves backward compatibility with a renamed task_orchestrator_id field mapped to parent_agent_id. This eliminates thousands of lines of dead code while maintaining all functional capabilities.

Embedding Cache for Search Performance

Added CachedEmbedder with LRU caching for OpenAI embedding API calls, eliminating redundant requests during search and entity creation. The cache uses normalized text keys (stripped, lowercased, hashed) with request deduplication for concurrent identical queries. Default cache size is 2000 entries (~12MB) with thread-safe async operations. Cache statistics track hits, misses, and evictions for monitoring.

Agent Command Center UI

Replaced traditional list-page navigation with a resizable three-pane layout at /agents:

• Navigator (left): Searchable agent list grouped by project
• Center Stage: Dashboard with approval queue and fleet overview, or agent chat when selected
• Inspector (right): Activity feed and fleet status, or agent detail view when selected

Eliminates content redundancy by assigning each pane a distinct role. Agent detail page now redirects to /agents?id=<uuid> for unified navigation.

Graph Visualization Improvements

Extended graph queries to include Document nodes alongside Episodic and Entity labels, enabling visibility of documentation pages linked via DOCUMENTED_IN relationships. Added project focus mode allowing users to filter visualization to selected projects (opt-in only). Shared project toggle now depends on focus mode being active. Graph integration tracks source_chunk_id during entity extraction for proper document linking.

Security Enhancements

RLS context failures now raise exceptions instead of continuing silently. All three RLS setup paths (get_rls_session, get_auth_session, apply_rls_from_auth_context) raise HTTPException(500) or RuntimeError when set_rls_context() fails, preventing cross-org data access when RLS policies permit NULL org_id.

Agent Framework

• Added WSEvent enum centralizing 25 WebSocket event names to prevent typos causing silent failures
• Introduced AgentConfig dataclass with per-agent-type SDK defaults for model, max_turns, max_budget_usd, and disallowed_tools
• All agents now default to claude-opus-4-6 model via AGENT_TYPE_CONFIGS mapping
• Parallelized quality gate execution using asyncio.gather() instead of sequential runs
• Added graceful error handling for individual gate failures without crashing entire gate run
• Fixed circular import in message_bus.py by deferring sibyl.jobs imports to function bodies
• Converted all f-string logging to structured structlog format in runner.py and orchestrator.py
• Made _derive_agent_tags async with lazy AsyncAnthropic client for non-blocking LLM calls
• Purged dead in-memory message queue system (AgentMessage class, _message_queues dict, messaging methods)
• Updated health checks to read last_heartbeat from AgentState in Postgres (authoritative source)
• Added TODO(agent-pool) annotations explaining intentionally stubbed agent pooling logic

Graph & Knowledge

• Fixed graph overlay displaying zero totals when project filtering is active by adding fallback logic
• Both backend (communities.py, graph.py) and frontend now use displayed counts when focused query undercounts
• Refactored graph totals and node fetching to use consistent _project_filter helper including Document nodes via DOCUMENTED_IN traversal
• Added project-level RBAC enforcement for related entities in RAG search with UUID parsing helper
• Document node creation uses MERGE with ON CREATE/ON MATCH clauses preserving existing properties
• Increased FalkorDB connection pool timeouts to 60-90s accommodating Graphiti's long-running operations
• Added retry logic to add_episode for transient Redis failures

Web UI

• Improved d3-force layout with adaptive forces based on node count preventing "starfield" dispersion
• Force strengths scale down for large graphs (900+ nodes: 0.4x, 500+ nodes: 0.55x)
• Auto-enable focus mode when project selection changes via header for immediate visual feedback
• Replaced custom linkCanvasObject with native linkColor/linkWidth callbacks for robustness
• Fixed GraphLink type to accept number indices per d3-force runtime mutation behavior
• Reset graph selection state when filters change and auto-fit after force simulation stabilizes
• Sync fullscreen state with browser API events for accurate toggle display
• Show loading/error states in spawn agent dialog project selector
• Fixed agent grouping to display "Loading..." while projects fetch
• Preserve metadata in agent model from_entity conversions for proper list_by_type filtering

API & Backend

• Added distributed locks to all task workflow endpoints (start, complete, block, unblock, review, archive) preventing concurrent state transitions
• The PATCH endpoint already had lock protection—workflow routes now match
• Fixed circular import in backups.py by moving imports to function bodies
• Updated 17 files (~60 call sites) to use WSEvent enum constants instead of raw strings
• Suppress noisy Claude SDK abort errors during agent termination
• Wait for running jobs before resume to avoid cancel scope issues
• Clear stale stop signals before execution preventing immediate termination on resume
• Fixed resume call to use runner.resume_agent() instead of deleted resume_from_checkpoint()

Infrastructure

• Fixed E2E tests to bypass host machine's project context causing access denied errors
• Added --all flag to search and task_list commands
• Updated web Dockerfile to add SIBYL_API_URL for server-side Next.js fetching
• Next.js Server Components now fetch from http://api:3334 (Docker network) instead of localhost:3334
• Addressed ruff linter warnings using raise ... from None, contextlib.suppress(), and nested with consolidation

Breaking Changes

None — This release maintains full backward compatibility. The task_orchestrator_id field is preserved in AgentRecord and mapped to parent_agent_id internally.

Upgrade Notes

No special upgrade steps required. Database migrations run automatically on API startup. Users with custom agent orchestration integrations should review the simplified parent-child model, though the old field names remain functional.

v0.2.6

Release Notes v0.2.6

Released: 2026-01-27

This release upgrades the build system to moon v2 and improves developer experience with dynamic version management, better context detection, and enhanced CI reliability.

Highlights

moon v2 Migration

Complete upgrade to moon v2 monorepo build system with modernized configuration schema. The new architecture uses toolchains.yml instead of toolchain.yml and replaces deprecated fields across all project definitions. Key changes include type → layer, platform → toolchains.default, local: true → preset: server, and vcs.manager → vcs.client for VCS configuration.

Dynamic Version Resolution

Version information now resolves dynamically from installed package metadata using importlib.metadata.version() instead of hardcoded strings. The sibyl --version and sibyl version commands read from the installed sibyl-dev package, ensuring displayed versions always match the actual installation. A new --version / -V flag provides quick CLI access.

Path-Based Context Display

The sibyl context command now detects and displays project information when working in a directory with path-to-project mappings but no active named context. The interface shows project name, progress bars, task status counts, and related metadata fetched from the graph, improving discoverability for users working in linked directories.

Build System

• Migrate from moon v1 to moon v2 with updated configuration schema across all projects
• Rename .moon/toolchain.yml → .moon/toolchains.yml with JavaScript/Node.js/pnpm sections
• Replace type field with layer (application, library, tool, configuration)
• Replace platform field with toolchains.default (node, system)
• Convert local: true to preset: server for non-cacheable tasks
• Update command → script for complex shell commands with pipes
• Add explicit Node.js and pnpm toolchain declarations (required in v2)
• Introduce defaultProject: root for unscoped task execution

Developer Experience

• Add __getattr__ lazy loading for __version__ attribute in sibyl_cli.__init__
• Create get_version() helper using pkg_version("sibyl-dev") with fallback
• Add --version / -V flag to main CLI callback with eager evaluation
• Implement _show_path_context() for rich project display without named context
• Fetch project details from API including metadata, status counts, and progress percentage
• Display progress bars and task status breakdowns (doing/blocked/review/todo)
• Show matched path and server URL when operating in path-mapped directories

CI/CD

• Add proto toolchain warm-up step before parallel CI tasks to prevent race conditions
• Run proto use --log debug to install all tools from .prototools upfront
• Verify uv --version after proto setup to confirm tool availability
• Fix shim permissions with chmod +x on proto directories
• Eliminate tool auto-install conflicts when multiple jobs run simultaneously

Docker

• Add SIBYL_API_URL environment variable to docker-compose.prod.yml for Next.js SSR
• Configure server-side API URL as http://backend:3334/api (internal container network)
• Fix missing /api suffix in docker-compose.quickstart.yml SSR URL
• Install Playwright Chromium in API Dockerfile for crawl4ai browser-based crawling
• Use minimal dependency list (~100MB) instead of --with-deps (~600MB with X11/GUI)
• Set PLAYWRIGHT_BROWSERS_PATH and ensure proper ownership for sibyl user

Upgrade Notes

This release requires no action from users. The version detection changes are transparent for production installs via uv tool install sibyl-dev. Docker images include all necessary Playwright dependencies for document crawling features.

Developers working on Sibyl itself should note the moon v2 configuration changes when adding new tasks or modifying existing ones. All task definitions now use the updated schema with layer, toolchains, and preset fields.

v0.2.5

Release Notes v0.2.5

Released: 2026-01-26

This release focuses on developer experience improvements with a new self-updater system, agent integration setup automation, and migration to Astral's ty type checker. The changes make Sibyl easier to install, update, and maintain while improving code quality across the codebase.

Highlights

Self-Updater for Easy Deployments

New sibyl update command checks and updates all Sibyl components with a single invocation. The updater handles CLI packages via uv tool upgrade, Docker container images via digest comparison, and agent skills/hooks through the integrated installer. Development mode detection prevents accidental updates when running from source, showing appropriate git instructions instead. Updates are opt-in only with confirmation prompts—no automatic updates or nagging.

Agent Integration Automation

The sibyl local setup command now automates installation of skills and hooks for Claude Code and Codex CLI. In development mode, the installer creates symlinks to the repository for live updates. In package mode, it copies embedded files from the package data directory. The installer handles both ~/.claude and ~/.codex directories, configures Claude Code hooks in settings.json, and displays a prompt snippet for users to add to their agent configuration files.

Type Checker Migration to ty

Migrated from pyright to Astral's ty type checker across all Python packages. ty catches more issues through stricter analysis while maintaining faster performance. The migration includes gradual adoption rules that treat most strict checks as warnings initially, per-file overrides for intentional patterns like monkey-patching and SQLAlchemy column comparisons, and targeted overrides for third-party library type stub limitations. All moon.yml typecheck tasks now use ty check instead of pyright.

Developer Experience

Installation & Setup

• New sibyl update command for checking and applying updates to CLI, containers, and skills
• Development mode detection shows git instructions instead of running updater
• Version checking via PyPI API with packaging.version comparison
• Docker Hub digest comparison for container update detection
• sibyl local setup automates skills and hooks installation for Claude/Codex
• Symlink mode for development vs copy mode for packaged installations
• Claude Code hook configuration in settings.json with backup of existing settings
• Install script now runs sibyl local setup automatically after CLI installation
• Added comprehensive tests for updater functionality in test_update.py

Skills & Documentation

• Added sibyl skill with comprehensive CLI command reference and workflow guidance
• Added agent-orchestrate skill for multi-agent task coordination patterns
• Skills include entity type references, task state machine documentation, and priority levels
• Added EXAMPLES.md and WORKFLOWS.md for skill usage patterns
• Session start and user prompt submit hooks for Claude Code integration
• Prompt snippets guide users on adding Sibyl to agent configuration files

Type Safety

• Migrated all Python packages from pyright to ty type checker
• Configured gradual adoption with most strict checks as warnings initially
• Added per-file overrides for SQLAlchemy column comparisons and FastAPI middleware
• Excluded third-party library stubs from strict checking (crawl4ai, arq, etc.)
• Removed ~100 stale type: ignore comments identified by ty
• Fixed sentinel pattern in state_sync.py using typed _Unset enum
• Added TypedDict for SyncResult in db/sync.py
• Constrained numpy>=2.4.1 to avoid yanked version 2.4.0

Graph Visualization

• Added shared knowledge toggle button to include/exclude shared project in graph view
• Automatic detection of shared project via metadata flags, slug, or naming conventions
• Filter state now properly resets selection when projects or types change
• Auto-fit graph after force simulation stabilizes for better initial view
• Fullscreen state syncs with browser API events for proper Escape key handling
• Edge query optimization filters by node set for better performance

Code Quality

• Replaced bare try-except-pass blocks with contextlib.suppress() for clarity
• Removed unused type ignore comments throughout codebase
• Fixed function name access on Callable types using getattr fallback
• Combined nested with statements for cleaner resource management
• Sorted __all__ exports in isort style
• Used raise ... from None for intentional exception replacement

Bug Fixes

CLI

• Removed MCP setup step from next steps display after sibyl local start
• Skills-based integration with CLI commands is now the recommended approach

Configuration

• Added artifacts = ["*.md", "*.py"] to pyproject.toml for proper package data inclusion
• Excluded data/ directory from pyright type checking in CLI package
• Updated constraint dependencies in root pyproject.toml for ty tooling

Technical Changes

Type System

• Replaced object sentinel pattern with typed _Unset enum in state_sync.py
• Added SyncResult TypedDict for structured sync operation results
• Removed redundant type: ignore annotations from graph client methods
• Fixed type narrowing with direct None checks instead of is not None patterns

Package Configuration

• CLI package now includes embedded skills and hooks in data/ directory
• Hatch build configuration includes non-Python files via artifacts setting
• Type checker configuration moved from per-package to workspace root
• Added 89 lines of ty configuration with rules and per-file overrides

Testing

• Fixed pytest-asyncio scope mismatch in graph integration tests
• Module-scoped async fixtures now use explicit loop_scope="module"
• Added pytest_asyncio.fixture decorator with matching scope declarations
• Test graph cleanup fixtures delete test graphs from FalkorDB after completion

Breaking Changes

None. This release maintains full backward compatibility with v0.2.4.

Upgrade Notes

For Easy Install Users

Run sibyl update to upgrade all components:

sibyl update           # Check and update everything
sibyl update --check   # Just check, don't apply
sibyl update --cli     # Only update CLI
sibyl update --yes     # Skip confirmation

For Development Users

Update dependencies and reinstall:

git pull
moon run install-dev

Install ty type checker:

uv add --dev ty

Agent Integration

Run sibyl local setup to install skills and hooks:

sibyl local setup

Add the displayed prompt snippet to your ~/.claude/CLAUDE.md or ~/.codex/AGENTS.md configuration file.

Dependencies

• Added ty>=0.0.10 as dev dependency
• Removed pyright from constraint dependencies
• Constrained numpy>=2.4.1 to avoid yanked version
• Added packaging for version comparison in updater

Contributors

Co-Authored-By: Claude Opus 4.5 noreply@anthropic.com
Co-Authored-By: Stefanie Jane

v0.2.4

Release Notes v0.2.4

Released: 2026-01-24

This release dramatically simplifies Sibyl's architecture while adding distributed agent execution capabilities. The over-engineered three-tier orchestration system has been removed in favor of a simpler recursive spawning model. A new distributed runner framework enables agent execution across multiple machines with intelligent task routing.

Highlights

Architecture Simplification: Orchestration Removal

Removed the complex three-tier orchestration hierarchy (MetaOrchestrator → TaskOrchestrator → Worker) that proved over-engineered for actual usage patterns. The new model uses simple parent_agent_id relationships for hierarchy, allowing any agent to spawn children recursively. Agents now self-manage review cycles, with learning captured through trajectory analysis rather than elaborate orchestration loops. This eliminates hundreds of lines of coordination code while maintaining flexibility.

Impact: Faster agent spawning, simpler codebase, easier mental model. The standalone flag distinguishes user-created agents from spawned children. Budget and depth limits provide control without heavyweight orchestration.

Distributed Runner Architecture

New apps/runner package enables agent execution across multiple machines. Runners connect to Sibyl Core via WebSocket for real-time task assignment, maintaining isolated git worktrees per project. Smart task routing scores runners based on project affinity (warm worktrees = 50 points), capability matching (30 points), available capacity (0-20 points), and health status (-100 penalty for stale heartbeat). Deploy via Docker with included Dockerfile and docker-compose.yaml, or install with Homebrew formulas for sibyl CLI and sibyl-runner daemon.

Impact: Scale agent execution horizontally. Runners with warm worktrees for a project are strongly preferred, reducing startup time. The TaskRouter class handles optimal assignment automatically.

Inter-Agent Communication System

New MessageBus class enables structured communication between distributed agents. Message types include progress updates, blocking queries, code review requests, blocker reporting, and work delegation. Messages persist in PostgreSQL (InterAgentMessage table from migration 0013) with real-time delivery via Redis pub/sub. CLI commands (sibyl agent progress, sibyl agent query, sibyl agent inbox, sibyl agent respond) enable agents to communicate during execution. Blocking queries use async polling with configurable timeouts (default 60s).

Impact: Agents can coordinate across machines, report blockers to orchestrators, request peer reviews, and delegate subtasks without manual intervention.

Developer Introspection Tooling

New log capture system stores recent logs in a 1000-entry ring buffer (LogBuffer singleton with thread-safe access). REST API endpoints (GET /logs, WebSocket /logs/stream) and CLI commands (sibyl logs tail, sibyl logs tail --follow) provide access to server logs without SSH. Debug commands (sibyl debug query "MATCH...", sibyl debug schema, sibyl debug status) enable read-only Cypher queries, entity type inspection, and unified health dashboards. All debug features require OWNER role for security.

Impact: Faster debugging during development. When tests fail mysteriously, sibyl logs tail -l error shows what happened. The structlog processor integration captures all log events automatically.

Performance Optimizations: Graph Layer

Removed Graphiti's semaphore throttling bottleneck that serialized both LLM API calls and FalkorDB queries. The _patch_semaphore_gather() function replaces semaphore_gather with plain asyncio.gather, eliminating 15+ second blocking on simple reads. FalkorDB concurrency is properly handled by BlockingConnectionPool (50 connections, 60s timeout) and Redis native concurrent query support. Also removed application-level write_lock semaphores since the connection pool already manages write concurrency. Increased socket timeouts to 120s to accommodate Graphiti's 60-90s add_episode operations under heavy load.

Impact: Bulk operations are dramatically faster. Project-scoped searches now include general knowledge (entities without project_id) alongside project-specific results.

Agent Lifecycle Improvements

New state_sync module keeps AgentState in Postgres synchronized with graph updates during spawn, resume, heartbeat, and completion. Stale working agents (no heartbeat in 5 minutes, no Redis job) are marked as failed on worker startup with error worker_crashed. Stop signals now cancel the execution task immediately via asyncio.Task.cancel() instead of waiting for the next message iteration. Activity hints (Reading config.py, Running tests) sync to current_activity field for real-time UI visibility. Session continuation works seamlessly—just send a message even if the agent finished.

Impact: Agents stuck in "working" state after crashes are automatically recovered. Stop signals terminate immediately regardless of what Claude is doing. Users see what agents are actively working on.

Distributed Execution

Runner Daemon

• Add sibyl-runner CLI with register, run, and status commands
• Implement ProjectRegistry for worktree management with auto-detected capabilities per project (python, node, rust, go)
• WebSocket client with automatic reconnection and exponential backoff
• Heartbeat acknowledgment and capacity management
• Store operational state (heartbeat, status, load) in PostgreSQL for fast queries
• Configuration at ~/.config/sibyl/runner.yaml with server URL, max concurrent agents, capabilities
• Homebrew formula (Formula/sibyl-runner.rb) includes launchd service for auto-start

Task Routing

• TaskRouter class scores runners for optimal assignment
• Routing factors: warm worktree affinity (50 points), full capability match (30 points), available capacity (0-20 points scaled by ratio), health penalty (-100 for stale heartbeat > 60s)
• CLI commands: sibyl runner list, sibyl runner route, sibyl runner scores
• REST endpoints: POST /runners/route, GET /runners/scores
• User-scoped routing ensures proper multi-tenancy isolation

Runner Management

• WebSocket handler at /runners/ws for real-time connections
• REST CRUD routes: register, list, get, update, delete
• PostgreSQL models: Runner, RunnerProject, AgentState, OrchestratorState (migration 0012)
• Graph entities track identity in FalkorDB via graph_*_id fields while operational state lives in Postgres
• Project registration tracks warm worktrees for affinity scoring

Agent Platform

Communication

• MessageBus class handles routing, persistence, and delivery
• Message types: progress, query, response, review_request, review_result, blocker, delegation, system
• Blocking query pattern: await bus.query() polls for response with timeout
• Message formatting functions (format_message_for_injection, format_messages_digest) for Claude Code session injection
• CLI: sibyl agent progress, sibyl agent blocker, sibyl agent query, sibyl agent delegate, sibyl agent review, sibyl agent inbox, sibyl agent respond, sibyl agent conversation

Orchestration Changes

• Remove MetaOrchestratorService, TaskOrchestratorService, WorkerPromotionService
• Remove orchestrator API routes and CLI commands (orchestrate, dispatch)
• Remove web UI orchestrator components (OrchestratorGroupCard, health monitor)
• Update AgentRecord: task_orchestrator_id → parent_agent_id (backward compatible)
• Remove entity types: META_ORCHESTRATOR, TASK_ORCHESTRATOR
• New fields: standalone (true if user-created), worktree_id (for cleanup tracking)
• Simplified approval handling without orchestrator callbacks

State Management

• state_sync module with update_agent_state() helper for Postgres/graph synchronization
• Naive datetime normalization (_to_naive()) for TIMESTAMP WITHOUT TIME ZONE columns
• Best-effort updates: logs warnings on failure instead of crashing execution
• Preserve metadata dict in from_entity() conversions for proper filtering in list_by_type queries
• Use typed model fields (project_id, agent_type) instead of reading from empty metadata dict

Lifecycle

• Stale agent cleanup: _cleanup_stale_working_agents() runs on worker startup
• Mark agents as failed if last heartbeat > 5 minutes and no Redis job exists
• Delete arq jobs from Redis when terminating to prevent auto-restart on worker reboot
• Clear stale stop signals before execution to prevent immediate termination on resume
• Wait for running jobs before resume to avoid cancel scope issues
• Add 60-second grace period for health checks during agent startup

Activity Tracking

• Generate human-readable activity hints from tool calls (Read, Write, Bash)
• Sync current_activity to agent state for real-time visibility
• Display current activity in UI when agent is working
• NEW badge for agents created in last 5 minutes
• Active status from heartbeat recency (within 2 minutes) not status field
• Sort order: NEW first, then active, then by recency

Developer Experience

Log Access

• LogBuffer singleton with thread-safe ring buffer (1000 entries, configurable)
• LogEntry dataclass: timestamp, service, level, event, context
• Subscriber pattern with asyncio.Queue for real-time streaming
• structlog processor integration captures all log events
• REST: GET /logs with pagination, service filter, level filter
• WebSocket: /logs/stream for real-time tail with auto-reconnect
• MCP tool: logs() for Claude Code access
• CLI: sibyl logs tail [-n NUM] [-l LEVEL] [-s SERVICE] [-f]

Debug Commands

• POST /admin/debug/query for read-only Cypher queries (OWNER only)
• GET /admin/dev-status aggregates API/worker/graph/queu...

v0.2.3

Release Notes v0.2.3

Released: 2026-01-13

This patch release fixes server-side rendering in the Next.js web application by adding proper API URL configuration for Docker environments.

🐛 Fixes

Next.js SSR Docker Configuration

Fixed SSR fetch failures in containerized deployments by introducing separate API URLs for server and client contexts. Next.js server components now use the internal Docker network address (http://api:3334) via SIBYL_API_URL, while client-side code continues using the public URL (http://localhost:3334) via NEXT_PUBLIC_API_URL.

This resolves the issue where SSR components couldn't reach the API during Docker Compose deployments because they attempted to use the client-side URL.

Changed:

• apps/cli/src/sibyl_cli/local.py — Add SIBYL_API_URL environment variable to web service configuration

v0.2.2

Release Notes v0.2.2

Released: 2026-01-13

This patch release fixes a critical server-side rendering (SSR) issue in the Next.js web application that prevented proper fetching from the API during SSR.

fix(config): add server-side API URL for Next.js SSR

Added SIBYL_API_URL environment variable to docker-compose.quickstart.yml and docker-compose.quickstart.test.yml to support server-side rendering. Next.js SSR components need to fetch from the internal docker network (http://api:3334) while client-side code uses the public URL (http://localhost:3334).

This resolves SSR fetch failures that occur when NEXT_PUBLIC_API_URL is used for both server and client contexts.

Impact:

• Web UI now correctly fetches data during SSR in Docker environments
• Eliminates connection errors in Next.js server-side components
• No changes required for local development or existing deployments (environment variable defaults handled gracefully)

Files Changed:

• docker-compose.quickstart.yml — Added SIBYL_API_URL for production quickstart
• docker-compose.quickstart.test.yml — Added SIBYL_API_URL for test environment

v0.2.1

Release Notes v0.2.1

Released: 2026-01-12

This patch release adds comprehensive backup management, automatic database migrations, and improved installation workflows. The focus is on operational reliability and deployment simplicity.

Highlights

Backup Management System

Complete backup functionality for PostgreSQL and FalkorDB graph data with scheduled automation and API management. Organizations can configure backup schedules, retention policies, and content options. Archives are compressed tar.gz files containing PostgreSQL dumps, graph exports, and metadata with SHA256 checksums for integrity verification.

Automatic Database Migrations

The API server now runs Alembic migrations automatically on startup, ensuring schema is always current before processing requests. Works in both Docker and development environments with automatic path detection.

Streamlined Installation

Interactive prompts removed from installation scripts. API keys are now read from environment variables, enabling fully automated deployments. The installation flow is simplified with better POSIX compliance and clearer error messages.

Infrastructure

• Add backup management with per-organization settings for schedule and retention
• Add REST API endpoints for triggering, listing, downloading, and deleting backups
• Add CLI commands (sibyld db backup-create, backup-list, backup-download)
• Add async job queue integration with arq for background processing
• Add cron-based scheduled backups with configurable retention cleanup
• Add database models for tracking backup records (backups and backup_settings tables)
• Add migrations.py module with async wrapper for Alembic command execution
• Integrate migration runner into FastAPI app lifespan hook
• Support both Docker and development environments via alembic.ini path detection

Version Management

• Centralize version in root VERSION file for single-source versioning
• Read version from VERSION file at runtime instead of hardcoding
• Root and health endpoints now return dynamic version
• Python packages use hatchling dynamic version from VERSION

Installation & Setup

• Remove interactive API key prompts from installation scripts
• Read API keys from environment variables (OPENAI_API_KEY, ANTHROPIC_API_KEY)
• Add warning when API keys not found in environment
• Use printf instead of echo -e for better POSIX compliance
• Fix command existence checks to redirect stderr properly
• Remove moon proto plugin (built-in since proto v0.45)
• Rename install_cli() to verify_cli() in setup-dev.sh
• Delete obsolete scripts/install.sh (functionality moved to root)

Docker

• Optimize build context with whitelist-first .dockerignore (3GB → 14KB)
• Copy VERSION file for hatchling build in both API and web Dockerfiles
• Silence git version detection in Docker (no git available)
• Update web Dockerfile workdir for correct standalone deployment structure
• Fix web build to use repo root context for proper pnpm workspace resolution

Web UI

• Fix login redirect to always include value (default to /)
• Add backup management UI with settings, status, and download functionality
• Add settings navigation for backup configuration

Backend

• Allow /setup route to bypass authentication middleware
• Fix FalkorDB episodes field type handling (null, list, or comma-separated string)

Breaking Changes

None.

Upgrade Notes

1. Run sibyld db migrate to create backup tables (happens automatically on startup)
2. Configure backup settings via API or web UI if automatic backups are desired
3. Set OPENAI_API_KEY and ANTHROPIC_API_KEY environment variables for new installations

v0.2.0

Release Notes v0.2.0

Released: 2026-01-10

Version 0.2.0 represents a major milestone in Sibyl's evolution as a collective intelligence runtime. This release delivers substantial improvements across authorization, performance, developer experience, and operational maturity. The focus is on production readiness through security hardening, performance optimization for large knowledge graphs, and enterprise-grade multi-tenancy support.

Highlights

Authorization Hardening with Row-Level Security

Complete security overhaul implementing PostgreSQL row-level security policies across all database tables. The new AuthSession pattern combines authentication context with RLS-enabled database sessions, ensuring data isolation at the database layer. API key scoping now supports project-level restrictions via api_key_project_scopes table.

Graph Performance Breakthrough

Optimized FalkorDB operations deliver 3300x faster edge searches (860ms → 0.26ms) through custom FalkorDBSearchInterface implementation. Added per-organization write semaphores to eliminate cross-org blocking, and new batch operations using UNWIND queries provide 50x faster bulk inserts (10s → 200ms for 100 entities).

Advanced Knowledge Retrieval

Introduced optional cross-encoder reranking for refined relevance scoring after RRF fusion. New temporal query support exposes Graphiti's bi-temporal model for point-in-time queries and knowledge timeline exploration. Conflict detection layer identifies potential contradictions before adding knowledge to maintain graph consistency.

Production-Ready Infrastructure

Centralized version management through root VERSION file with hatchling integration for Python packages. Unified release workflow automates versioning, quality checks, and AI-powered release note generation via git-iris. PyPI publishing now uses trusted publishing with OIDC (no tokens needed).

Build & Release Infrastructure

Version Management

• Centralized version control using root VERSION file as single source of truth
• Python packages use hatchling dynamic versioning from VERSION file
• Web app reads VERSION at build time via next.config.ts
• Runtime version appends git hash for dev builds (e.g., "0.1.0+gabc123")
• Clean version strings for release builds

CI/CD Workflows

• Unified release.yml workflow with automatic patch/minor/major bumps
• Consolidated publish.yml for PyPI packages and Docker images
• AI-powered release notes generation via git-iris integration
• Docker builds now copy VERSION file for both API and web containers
• GitHub Actions docs deployment pipeline for VitePress documentation

Build System

• Removed moon Python toolchain to prevent venv conflicts with uv
• Simplified sync task by removing redundant venv creation step
• Fixed CI to use moon run instead of moon ci to avoid cleanup failures
• Streamlined Docker workflows: only build on releases and manual dispatch

Package Distribution

• Renamed PyPI package from sibyl-cli to sibyl-dev (CLI command remains sibyl)
• PyPI publishing uses pypa/gh-action-pypi-publish with OIDC trusted publishing
• Added install.sh bootstrap script for one-liner installation
• Docker build context switched to repo root for proper pnpm workspace resolution

Authorization & Security

Row-Level Security Implementation

• PostgreSQL RLS policies enforced across all tables with organization_id
• Session variables (app.user_id, app.org_id) set automatically via set_config()
• Migrated route modules to unified AuthSession pattern: agents, users, tasks, approvals
• Added get_auth_session() dependency combining auth context with RLS-enabled session
• Fixed RLS migration to exclude tables without direct organization_id column

API Key Security

• API key project scopes enforced in MCP tools via api_key_project_scopes table
• MCP tools extract user_id from JWT/API key tokens for access control
• Admin users with restricted API keys limited to allowed projects
• Added _get_accessible_projects() to filter results by user permissions

Setup & Configuration Security

• Setup endpoints gated after initial setup via require_setup_mode_or_auth
• /setup/validate-keys and /setup/mcp-command require authentication post-setup
• First user automatically becomes admin via is_admin field and migration
• Server config management: POST /setup/config for admin-only API key updates

Web Security

• Disabled Next.js server-side data caching to prevent cross-user leakage
• Switched to cache: 'no-store' for user-specific fetch functions
• Client-side React Query caching provides per-session data freshness

Graph & Performance

FalkorDB Optimizations

• Custom FalkorDBSearchInterface for edge fulltext search: 3300x faster (860ms → 0.26ms)
• Eliminates O(n²) cartesian products using startNode(rel)/endNode(rel) directly
• Per-organization write semaphores prevent cross-org blocking
• Global write_lock retained for backward compatibility (deprecated)
• Added OrgWriteContext async context manager for convenient write locking

Batch Operations

• New batch.py module for efficient bulk graph operations using UNWIND queries
• batch_create_nodes: Create N nodes in 1 query (was N queries)
• batch_create_relationships, batch_update_nodes, batch_delete_nodes
• Performance: 50x faster for bulk inserts (100 entities: 10s → 200ms)
• Includes serialization helpers for datetime, enum, nested dicts

Concurrency Fixes

• Fixed 44-second index rebuild on every FalkorDriver.clone() call
• Monkey-patched clone() to use copy.copy() instead of creating new instances
• Fixed FalkorDBSearchInterface to delegate to Graphiti's default implementations
• FalkorDB write concurrency managed via semaphore to prevent corruption

Knowledge Retrieval

Cross-Encoder Reranking

• Optional cross-encoder reranking after RRF fusion for refined relevance scoring
• New reranking.py module with CrossEncoderConfig for enable/disable, model selection
• Default model: cross-encoder/ms-marco-MiniLM-L-6-v2 (fast, accurate)
• Disabled by default (opt-in for performance-sensitive workloads)
• Graceful fallback on error with 23 comprehensive tests

Temporal Queries

• Bi-temporal query support exposes Graphiti's temporal model
• New tools/temporal.py with history/timeline/conflicts modes
• Point-in-time queries with as_of filtering via get_entity_history()
• Timeline exploration showing all edge versions over time
• Bi-temporal semantics: created_at/expired_at (system time), valid_at/invalid_at (real-world time)
• CLI: sibyl entity history <id> [--as-of DATE] [--mode MODE]

Conflict Detection

• New conflicts.py module detects contradictions before adding knowledge
• Semantic search for existing facts via find_similar_entities()
• Classification: duplicate (>95% similarity), potential_contradiction, semantic_overlap
• Returns warnings for user review rather than blocking
• Applied to episode, pattern, rule, template types (not tasks/projects)

API Improvements

Error Handling

• New error factory functions in api/errors.py for cleaner exception handling
• Factories: not_found(), bad_request(), forbidden(), conflict(), unauthorized()
• Entity-specific helpers: agent_not_found, task_not_found, epic_not_found
• generate_error_id() for 8-character tracking IDs
• Route handler decorators: @handle_not_found, @log_operation, @require_state, @with_error_context

Dependency Injection

• New api/dependencies.py with FastAPI dependencies for graph operations
• get_entity_manager(): EntityManager scoped to current organization
• get_relationship_manager(): RelationshipManager scoped to current organization
• Eliminates repeated 2-line pattern for manager instantiation

Async Job System

• Pending entity registry for async operation queueing via pending.py
• Track entities being created asynchronously with 5-minute TTL
• queue_pending_operation() queues operations to run after materialization
• Fixes race condition: create_task(async) + add_note no longer fails
• NoteResponse gains optional status="pending" field

Utilities

• Metadata access utilities in sibyl_core/utils/metadata.py
• Functions: get_metadata(), safe_meta(), safe_attr(), has_meta(), match_meta()
• Eliminates 40+ instances of (entity.metadata or {}).get() patterns

Workflow & Task Management

Epic & Task Enhancements

• Epics auto-start when tasks begin progress (doing/review/blocked states)
• Mirrors existing auto-complete behavior when all tasks finish
• Comprehensive epic show with full context: metadata, description, learnings, tasks by status
• Related knowledge from graph traversal (patterns, rules) with project indicators
• Todo queue showing up to 20 tasks sorted by priority with visual markers
• Removed title truncation from task and epic tables

CLI Improvements

• Added sibyl upgrade command with auto-detection of installation method
• Options: --check for updates, --pull for Docker images
• Git worktree resolution: detects worktrees via .git file and resolves to main repo
• Added sibyld db migrate command (renamed from init-schema)
• Improved epic list table with full-width expansion and natural wrapping

Project Management

• Shared project pattern: each org has special _shared project for org-wide knowledge
• New is_shared boolean on Project model with migration
• Shared projects use visibility=ORG and default_role=VIEWER
• backfill_shared_project() reassigns orphan entities to shared project
• CLI: sibyld db backfill-shared-projects --org-id UUID

Web UI

State Persistence

• Generic storage utilities in lib/storage.ts with readStorage/writeStorage
• React hooks: useClientPrefs and useUrlPrefs for client-side preferences
• Epics page persists status ...