v1.5.4rc1 — Hybrid Retrieval, Structured Evidence, and Safer MCP Packaging

Release Date: 2026-09-15
Changes: v1.5.4 → v1.5.4rc1

Pull Requests: #4339, #4580, #4613, #4630, #4859, #4877, #4886, #4891, #4899, #4928, #4929, #4930, #4931, #4933, #4934, #4935, #4936, #4937, #4944, #4945, #4950, #5030, #5032, #5034, #5035, #5038

Summary

This release improves hybrid search and evidence handling, adds a context‑primed query decomposition retriever, ensures packaged extensions ship with the PyPI wheel, and tightens server and telemetry hardening. Together these changes make search results more accurate and traceable, reduce setup friction, and improve security and reliability for multi-component deployments.

Highlights

• New HybridDecompositionRetriever: context-primed query decomposition for better hybrid search.
• Hybrid completion now returns structured context evidence (machine-readable provenance).
• Document external metadata is preserved on chunks and surfaced during hybrid retrieval so results include source details.
• Release wheel is now built from the source tree so bundled extensions are included in pip installs.
• MCP (service) hardening, auth fixes, and telemetry redaction for safer deployments; MCP client published to PyPI.

New Features

• HybridDecompositionRetriever — WHAT: a new retriever that decomposes a user's question into smaller, focused sub-queries using the surrounding context (context-primed decomposition). WHAT IT DOES: it sends those sub-queries to the retrieval system and combines their results. WHY IT MATTERS: decomposing complex queries helps the system find more relevant evidence across documents, improving answer quality for multi-part or ambiguous questions.
• Structured context evidence from HYBRID_COMPLETION — WHAT: hybrid completion mode now returns evidence in a structured, machine-readable form (not just text). WHAT IT DOES: callers receive rich evidence objects with content and provenance information. WHY IT MATTERS: client applications can display reliable source snippets, attach provenance to answers, or programmatically filter and rank returned evidence.
• Document external_metadata stamped on chunks — WHAT: when a document is split into searchable chunks, the document's external metadata (user-provided fields like source, id, tags) is preserved on each chunk. WHAT IT DOES: that metadata is now available and surfaced during hybrid retrieval. WHY IT MATTERS: you can trace search hits back to the original document, filter results by source attributes, and build more transparent UIs.
• LLM-free GLiNER graph extraction backend — WHAT: a new optional graph extraction backend that does relation extraction without calling an LLM. WHAT IT DOES: extracts graph nodes/relations more cheaply and deterministically. WHY IT MATTERS: reduces cost and latency for structured information extraction, useful in batch pipelines or when LLM calls are constrained.
• Typed edges for custom models in the graph — WHAT: the graph data model supports typed edges (relation types) from custom extraction models. WHAT IT DOES: lets extraction outputs declare relation types so the graph stores richer, typed relationships. WHY IT MATTERS: enables stronger querying and visualization of extracted relations, making downstream reasoning and graph queries more useful.

Improvements

• Wheel packaging from source tree — WHAT: the release wheel is now built from the source tree so bundled extensions (extra plugins shipped in the repo) are included. WHAT IT DOES: pip installs of the package include those extensions automatically. WHY IT MATTERS: reduces manual post-install steps and prevents missing extension errors for end users.
• MCP client and server changes — WHAT: multiple hardening and usability improvements to the MCP client/server (including a new PyPI package for cognee-mcp). WHAT IT DOES: improves deployment and auth behavior for the multi-component control plane. WHY IT MATTERS: easier installation and more robust operation for deployments that use MCP.
• Permissions lookup scoped to tenant — WHAT: role and permission lookups are now restricted to the tenant (multi-tenant scope). WHAT IT DOES: prevents cross-tenant role leakage. WHY IT MATTERS: improves security and correctness for multi-tenant installations.
• Preserve LLM budget and fallback behavior — WHAT: fixes that keep budget detail (usage/cost metadata) and preserve configured model fallbacks when a request is rejected due to budget or policy. WHAT IT DOES: reporting and fallback model selection behave more predictably. WHY IT MATTERS: you’ll get accurate budget visibility and more reliable model fallbacks under constrained conditions.
• Retrieval scoring fix for bounded queries — WHAT: neighborhood IDs (neighboring results) are properly scored in bounded queries. WHAT IT DOES: improves scoring accuracy when retrieval is constrained to a neighborhood. WHY IT MATTERS: search relevance improves for neighborhood-based queries such as graph or local-context searches.
• Record every QA turn in session history — WHAT: session/QA history now records each turn reliably. WHAT IT DOES: conversation logs and histories include every question/answer in order. WHY IT MATTERS: better auditing, debugging, and UI displays of conversational sessions.

Performance

• Reduced friction when installing extensions — because the wheel now includes bundled extensions, setup time is reduced and runtime issues from missing extensions are less likely.
• Lower extraction cost/latency option — the LLM-free GLiNER backend offers a faster, cheaper path for graph extraction in large batch jobs.

Security

• X-Api-Key authentication support in API mode — WHAT: the API now supports X-Api-Key as an authentication scheme. WHAT IT DOES: allows simpler API key use by some deployment platforms. WHY IT MATTERS: increases interoperability with standard API gateway setups.
• Telemetry redaction for provider aggregates — WHAT: identifiers are redacted from telemetry aggregates. WHAT IT DOES: prevents leaking user or tenant identifiers in aggregated telemetry. WHY IT MATTERS: improves privacy and compliance for telemetry data.
• MCP server hardening and test coverage — WHAT: several changes harden MCP server behavior and tests. WHAT IT DOES: tightens auth handling and error cases. WHY IT MATTERS: reduces attack surface and improves operational reliability.

Bug Fixes

• Stop first-run hints repeating their "Fix" label — WHAT: UI/help text duplication fixed. WHY IT MATTERS: clearer onboarding messages.
• Raise typed 404 when forgetting an unknown dataset — WHAT: calling forget on a non-existent dataset now returns a typed 404 instead of an internal error. WHY IT MATTERS: clearer errors when automating dataset deletion.
• Restore auth re-export that a reimport clobbered — WHAT: fixed an import regression that impacted auth exports. WHY IT MATTERS: restores expected auth behavior for clients.
• Point API reference playground at a reachable base URL — WHAT: docs now link to a working API playground. WHY IT MATTERS: fewer docs dead-ends when exploring the API.
• Fixes for examples and extraction demos — WHAT: several example and demo fixes that prevent extracted nodes or containers from being dropped, correct comments, and ensure pipelines run as expected. WHY IT MATTERS: better developer experience when following examples.
• Preserve gemini fallback and classify budget exhaustion correctly — WHAT: fixes so fallback model selection and budget error types behave correctly. WHY IT MATTERS: more predictable LLM selection and error handling.

Technical Changes

• Large API surface updates: many new and updated API routes and DTOs were added (search, recall, remember, sync, update, visualize, sessions, and more). These add functionality for hybrid retrieval and the web UI but are backward-compatible for normal clients.
• Many CI and workflow updates: expanded GitHub Actions workflows, release/test automation, and packaging scripts (including release wheel build steps).
• Database migrations and schema evolutions added across several migrations — upgrades may include new tables and indexes (typical for a server upgrade).
• Refactors and internal cleanups: removed unused Graphiti integration, tightened docstrings and examples, and improved test coverage across retrieval and MCP components.

Compatibility

— The Cognee Team · 2026-09-15