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

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

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

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