Skip to content

v1.3.0

Choose a tag to compare

@github-actions github-actions released this 02 Sep 22:31
· 376 commits to main since this release

Release Notes 1.3.0

Released: 2026-09-02

Sibyl 1.3 is the One Surface release: the API, CLI, web app, and MCP server now share one decomposed service layer instead of three drifting copies of the same logic. Alongside the restructure, this release fixes a class of writes that silently kept serving old data, makes typed relation predicates writable so traversal weights finally have a producer, and adds a naive-strong control arm so retrieval quality can be measured against an unweighted baseline.

Graph schema moves from version 19 to 20 and rewrites persisted rows on first boot. Read the Upgrade Notes before deploying.

Highlights

One Surface: a single service layer behind every entry point

entities.py and memory.py split into 15 focused route modules (entity_reads.py, entity_mutations.py, entity_policy.py, memory_promotion.py, memory_sharing.py, memory_spaces.py, and others), sibyl_core.services.graph and services.memory split into per-concern owners, and the CLI's monolithic client.py split into client_auth.py, client_graph.py, client_memory.py, client_transport.py, and siblings. Public contracts are unchanged; the duplication that let REST, MCP, and CLI answer the same question differently is gone.

Writable typed predicates with real traversal weights

supersedes, contradicts, requires, supports, and decides can now be declared on writes via related_to, defined in sibyl_core/models/relations.py. Each carries an expansion weight (requires 0.98, supersedes 0.95, supports 0.94, contradicts 0.64, decides 1.00) and a hybrid multiplier. supersedes and contradicts are suppressing predicates and require read visibility on the target before they can be minted.

Supersession and correction actually reach retrieval

Previously a SUPERSEDES edge pointed from the new memory to the retired one, so graph expansion walked outward and scored the retired row at the highest weight: saying "B replaced A" boosted A. Expansion now excludes SUPERSEDES unless the caller names it, and context_search() admits on two independent signals (lifecycle metadata and inbound supersession edges). Corrections on raw captures cascade to graph projections through projection/reconcile.py, with a revision-fenced write loop so a concurrent write cannot land unstamped.

Naive-strong control arm, selectable end to end

A new naive retrieval mode (sibyl_core/retrieval/naive.py) fuses three lanes (node fulltext, episode fulltext, node vector) with reciprocal rank fusion at NAIVE_RRF_K = 60.0, the RRF paper default and the arm's only tunable. It is selected through retrieval_mode: "fast" | "accurate" | "naive" on the context request, and it refuses the machine's tuning knobs so the control cannot quietly become the treatment.

Query-side morphology now comes from the index's own stemmer

Two hand-written tables (a 20-entry alias map in query_anchors.py, a 41-entry map in fact_frames.py) are replaced by snowballstemmer, the same Snowball English algorithm the SurrealDB snowball(english) filter runs. Checked against an embedded store over 4000 dictionary words, Python and the engine agree on every one, so a term the fulltext lane matched is the term the coverage ranker looks for. The 49-pair graded adjective table survives with a test proving Snowball unifies none of it.

Retrieval and Performance

  • Entity fulltext split into per-field top-k queries. The old single four-field math::max disjunction was the single most expensive call in the release A/A web run: 951 calls at p50 12.9s, because SurrealDB scored every matching row across all four indexes before LIMIT applied. graph_entity_search._fulltext_search now issues one bounded query per field in _FULLTEXT_FIELDS (name, summary, description, content) via asyncio.gather, merges on max score per uuid, then truncates. Tests pin that the merged ranking is identical to the single-statement ranking at limits 1, 2, 3, and 10.
  • Keyword boost matches tokens, not substrings. Snowball rewrites terminal y to i, so battery stems to batteri, which is a substring of nothing. The boost now tokenizes entity text through the same normalizer and intersects stems.
  • Batched graph reads and writes. GraphEntityStore.get_many() delegates to the manager's native bulk reader instead of fanning one coroutine per id, and embedding backfill batches its indexed HNSW updates instead of saturating every SurrealDB pool socket and starving auth handshakes.
  • Context packs scaled for the release corpus and graph-only packs no longer fall through to raw memory.

Memory Correctness

  • Deleted memories stop serving their text. The passage retire sweep walked to the first absent index and stopped, so a delete with a hole at index 0 left every span searchable. The sweep now covers the full MAX_PASSAGES_PER_SOURCE range, retries failures, and returns a PassageRetirement carrying failed_indices and failed_passage_ids. Deletion retires spans before removing the parent, so a partial sweep is re-enterable, and failed reprojection now answers 500 instead of a false 200.
  • Metadata deletions stick. Entity metadata was stored twice, flattened and as a JSON snapshot, and UPDATE ... MERGE only touched the flattened copy, so the read path resurrected deleted keys from the frozen snapshot. New writes no longer emit the snapshot, legacy rows heal in the same write, and upserts merge attributes in SurrealQL rather than replacing the whole bag.
  • Retrieval-key and scope clearing reaches promoted columns, not just the attributes bag.
  • Synthesis self-feeding guard holds at materialize time, matched on metadata keys rather than source references, with explicitly requested artifact_ids still exempt.

API, MCP, and Auth

  • MCP server and clients migrated to SDK 2 (mcp>=2.0.0,<3). FastMCP is replaced by MCPServer, the standalone SibylMcpTokenVerifier is gone in favor of SibylMcpOAuthProvider.load_access_token(), and the streamable HTTP app is constructed with TransportSecuritySettings so DNS-rebinding protection is on by default, allowlisting loopback, the bind address, and configured public origins.
  • WebSocket auth is header or cookie only. /api/logs/stream?token=<jwt> no longer authenticates. Both the log stream and the main event socket route through resolve_active_websocket_claims() in sibyl/auth/websocket.py, which reads the Authorization header or the sibyl_access_token cookie and verifies the session is still active.
  • Broadcast fan-out is concurrent, with disconnect cleanup gathered rather than serialized.
  • The relational RLS shim is deleted (sibyl/auth/rls.py), along with the in-process sibyl/cache.py layer.

CLI

  • 19 write refusals now exit non-zero. Invalid --type filters, empty task update / epic update, out-of-range explore traverse depth, failed synthesis verify verdicts, crawl link-graph errors, pending-writes discard with no match, unhealthy health output, and others previously printed a refusal and exited 0. A shared print_json_result(data, *, succeeded=...) helper keeps the JSON payload intact while raising typer.Exit(1), and apps/cli/tests/test_exit_codes.py pins each tail.
  • Buffered writes replay automatically. client_transport.py retries pending writes with exponential backoff from AUTO_REPLAY_BACKOFF_BASE_SECONDS (2s) to AUTO_REPLAY_BACKOFF_MAX_SECONDS (300s), up to AUTO_REPLAY_LIMIT (8) per batch. A write is not eligible for its first replay attempt until it is AUTO_REPLAY_GRACE_SECONDS (30s) old.
  • Pending writes are bound to credential lineage, so a buffered write cannot replay under a different identity than the one that created it.
  • Auth URL precedence is fixed and pending-write state is visible in command output.
  • Config writes are crash-durable (sidecar lock plus atomic replace) and corrupt pending writes are preserved rather than silently dropped.

Web

  • The monolithic lib/api.ts and lib/hooks.ts split into per-domain modules (api/auth.ts, api/graph.ts, api/memory.ts, api/work-items.ts, hooks/realtime.ts, hooks/query-keys.ts, and siblings), with data-layer-contract.test.ts holding the boundary.
  • The graph page is rebuilt from graph-canvas.tsx, graph-toolbar.tsx, graph-data.ts, cluster-legend.tsx, and use-graph-page-state.ts, each with its own tests.
  • lib/constants.ts and lib/constants/index.ts barrels are removed; import from the domain module directly.
  • Vitest config moves to vitest.config.mts.

Release Engineering and Evals

  • The v1.3 LongMemEval decision rig is sealed: paid provider accounting, runtime provider boundaries, official prompt artifacts, source identity binding, and saved memory state are all pinned, with the release A/A executed from .github/workflows/longmemeval-v2-release-aa.yml.
  • The A/A run is recorded as rig-blocked. benchmarks/results/longmemeval-v2-release/sibyl-v1-3-aa-rig-blocked-receipt.json records status RIG_BLOCKED with reason dispatch_exhausted across five controller dispatches, completed_pass_count: 0, and score_claim_allowed: false. No benchmark score is claimed for 1.3.0.
  • New release tooling lands under tools/release/ (ci_changes.py, release_notes.py, version.py) and tools/trust/gate_runner.py, with version-pin sync tasks explicitly excluded from task caching.
  • docs/architecture/SIBYL_1_3_RELEASE_RUNBOOK.md and docs/admin/releasing.md document the gates, publication channels, and rollback rules.
  • SurrealDB ops jobs in the Helm chart run shell-free against the HTTP API, and the web runner image refreshes its Alpine packages.

Breaking Changes

  • WebSocket query-parameter tokens are rejected. Any client connecting to /api/logs/stream?token=<jwt> must switch to an Authorization: Bearer header or the sibyl_access_token cookie. sibyl logs -f already does this.
  • sibyl.cache is removed. QueryCache, LRUCache, CachedEntityManager, cached_search, cached_entity, invalidate_on_mutation, get_cache, and reset_cache no longer exist. Caching lives at the persistence boundary.
  • sibyl.auth.rls is removed. RlsSession, AuthSession, get_rls_session, require_rls_session, get_auth_session, and apply_rls_from_auth_context are gone; use AuthContext directly.
  • The sibyl db subcommand is retired along with the embedded Falkor/Cypher repair remnants. Use the chart's SurrealDB ops jobs.
  • MCP clients must speak SDK 2. Servers pinned to fastmcp<2 will not load against this release.
  • Web @/lib/constants barrels are gone. Import from the specific domain module.
  • Benchmark note distillation is removed (benchmarks/longmemeval_v2_memory/note_distillation.py); the production path is query-time operational distillation only.

Upgrade Notes

Take a verified backup before upgrading. 1.3.0 changes persisted state.

  • Graph schema migration 20 applies automatically at bootstrap. GRAPH_SCHEMA_CURRENT_VERSION moves from 19 to 20, and schema.py adds SchemaMigration(version=20, name="relation_created_at_cursor"). It runs DEFINE FIELD OVERWRITE created_at on relates_to and mentions, then rewrites data: string cursors are coerced to datetime, and rows with a missing or non-datetime cursor are set to time::now(). Defaults do not repair rows created before a field definition, so this normalization is what lets lifecycle keyset scans trust the cursor. There is no manual command; it runs on first boot of the new version and is not reversible without a restore.
  • Quality metadata is backfilled in the same pass. MEMORY_QUALITY_METADATA_MIGRATION_DEFINITIONS now fills attributes.importance and attributes.confidence from the legacy keys (retention_importance, memory_importance, promotion_confidence, reflection_confidence, projection_confidence, share_confidence) on both entity and relates_to, writing only where the canonical key is absent.
  • Plan for migration time proportional to relation and mention count. Both UPDATE sweeps touch every row that needs normalizing.
  • Update deployment pins: Sibyl chart 1.3.0, SurrealDB chart 1.3.0 (SurrealDB 3.2.3), API and web images 1.3.0.
  • Update the development toolchain if you build locally: proto 0.61.1, moon 2.5.3, Python 3.13.15, Node 24.19.0, pnpm 11.23.0, uv 0.12.5.
  • Audit integrations for imports of sibyl.cache and sibyl.auth.rls, WebSocket clients passing ?token=, MCP clients on SDK 1, and web imports of @/lib/constants.
  • Scripts that treated CLI exit code 0 as success will now see failures they were previously swallowing. This is the intended behavior; check CI jobs that wrap sibyl commands.
  • Do not quote a LongMemEval score for 1.3.0. The sealed receipt forbids it.

Rollback

v1.2.2 is the last known-good version on every channel: the v1.2.2 git tag, the GitHub release and its 17 evidence assets, ghcr.io/hyperb1iss/sibyl-api:1.2.2 and ghcr.io/hyperb1iss/sibyl-web:1.2.2 (plus the Docker Hub mirrors, with Cosign receipts), sibyl-core==1.2.2 / sibyl-dev==1.2.2 / sibyld==1.2.2 on PyPI, the sibyl-homebrew-1.2.2.rb formula, the sibyl 1.2.2 PKGBUILD, and Helm charts sibyl --version 1.2.2 and sibyl-surrealdb --version 1.2.2.

A runtime rollback means redeploying the 1.2.2 image and chart pins above. Because 1.3.0 changes persisted state through schema migration 20, restore data only from a verified backup; rolling the code back does not undo the rewritten created_at values or the backfilled quality metadata. Once the tag or any package is public, do not move the tag or replace an immutable artifact: mark the release a prerelease, pause the remaining channels, and fix forward with 1.3.1.

Install

Local server

curl -fsSL https://raw.githubusercontent.com/hyperb1iss/sibyl/main/install.sh | sh -s -- --version 1.3.0

Remote CLI

curl -fsSL https://raw.githubusercontent.com/hyperb1iss/sibyl/main/install.sh | sh -s -- --remote --version 1.3.0
sibyl init --remote https://sibyl.example.com
sibyl auth login

Homebrew

brew install hyperb1iss/tap/sibyl
sibyl up

Arch Linux (AUR)

paru -S sibyl
sibyl up

Headless server

curl -fsSL https://raw.githubusercontent.com/hyperb1iss/sibyl/main/install.sh | sh -s -- --version 1.3.0 --no-open

Kubernetes (Helm)

helm repo add sibyl https://raw.githubusercontent.com/hyperb1iss/sibyl/gh-pages
helm repo update sibyl
helm upgrade --install sibyl sibyl/sibyl --version 1.3.0

Artifacts

This release includes Python wheels and sdists, the generated
Homebrew formula, the generated AUR PKGBUILD, Helm charts, Docker
SBOMs, aggregate dual-registry cosign receipts, and a SHA256 checksum
manifest.