Qdrant — Semantic Memory

Platform 9 of 12·OS Layer 7 (Memory & Data Layer)·Required in all deployment modes

Scope of this page. Reference material for the Qdrant platform: what it is, what it is normally used for, and how and why Synedrix OS uses it. It is descriptive, not normative — where this page and a canonical spec in docs/os/ disagree, the canonical spec wins. Platform responsibilities are set by Tech Stack §8; the live deployment this page draws its worked example from is specified in DGX Vercel Chat Agent Deployment.

What Qdrant is link

Qdrant is a vector database. Its documentation frames the purpose as vector search that “goes beyond keyword matching to find data based on semantic meaning”: unstructured data is turned into “dense vector embeddings” and mapped into a “high-dimensional vector space” where semantically similar items cluster together.

The data model is small and consistent:

Distance metrics. Four are supported: Dot, Cosine, Euclid, Manhattan. Cosine similarity is implemented as dot-product over normalised vectors, with normalisation applied automatically at upload.

Payload filtering clauses. Conditions combine under three logical operators, which nest recursively: must — “The clause becomes true only if every condition listed inside must is satisfied”; should — “true if at least one condition listed inside should is satisfied”; must_not — “true if none of the conditions listed inside must_not is satisfied”. Condition types include exact match, match-any/match-except, numeric range, full-text and prefix matching, geo bounding-box/radius/polygon, nested filters, and structural checks (is_empty, is_null, has_id, has_vector, values count).

Filtered search — why it is the load-bearing feature link

Synedrix OS assigns Qdrant “metadata-aware filtered vector queries” specifically, so the mechanism matters. Qdrant’s documentation states the problem plainly:

“In the case of high-selectivity (weak) filters, you can use the HNSW index as it is. In the case of low-selectivity (strict) filters, you can use the payload index and do a complete rescore. However, for cases in the middle, this approach does not work well.”

Its answer is a filterable HNSW index. Qdrant extends “the HNSW graph with additional edges based on indexed payload values. Extra edges allow you to efficiently search for nearby vectors using the HNSW index and apply filters as you search in the graph.”

The consequence is architectural, not cosmetic: filtering happens during graph traversal, in a single pass, rather than as a pre-filter that narrows the candidate set before search or a post-filter that discards results after it. A tenant scope, a document class or a date window can therefore be expressed as a filter without silently degrading recall the way post-filtering does.

The dense vector index itself is HNSW (Hierarchical Navigable Small World), a multi-layered graph tuned by m (maximum node degree), ef_construct (search range during index build) and ef (search range at query time).

Quantization link

“Quantization is an optional feature in Qdrant that enables efficient storage and search of high-dimensional vectors.” It transforms vectors into compressed representations that preserve relative distances. Three methods are documented:

Hybrid and multi-stage queries link

Qdrant’s Query API composes retrieval strategies through a prefetch parameter: “Whenever a query has at least one prefetch, Qdrant will: 1. Perform the prefetch query (or queries), 2. Apply the main query over the results of its prefetch(es).” Prefetches nest.

Two fusion methods are documented for combining result sets. Reciprocal Rank Fusion (RRF) considers “the positions of results within each query and boosts those that appear closer to the top in multiple sets of results”. Distribution-Based Score Fusion (DBSF) “keeps the raw scores from each query but normalizes their distributions before combining”.

The same mechanism supports multi-stage retrieval: “First, use a smaller and cheaper representation to get a large list of candidates. Then, re-score the candidates using the larger and more accurate representation.”

Snapshots link

“Snapshots are tar archive files that contain data and configuration of a specific collection on a specific node at a specific time.” They exist at two levels: collection snapshots, containing a single collection’s configuration, points and payloads (but not its aliases), and full storage snapshots, covering all collections including aliases — the latter limited to single-node deployments and unsupported in distributed mode. Documented uses are data archiving, replicating a deployment, and migrating data between clusters.

What Qdrant is normally used for link

The general-purpose cases Qdrant’s own documentation leads with:

• Semantic search — retrieval by meaning rather than keyword overlap, over documents, code, or any content with a usable embedding.
• Retrieval-augmented generation — supplying an LLM with grounded context retrieved from a collection at query time.
• Hybrid search — combining semantic and lexical matching through sparse and dense vectors fused with RRF or DBSF.
• Recommendation and relevance feedback — collaborative filtering and similarity-driven exploration over the same vector space.
• Multi-modal and multi-representation retrieval — separate image and text embeddings attached to one point via named vectors.

The common thread is that Qdrant owns nearest-neighbour retrieval over embeddings, with metadata constraints applied inside the search. It does not own the embedding model that produced the vectors, and it is not the system of record for anything it stores.

How Synedrix OS uses it link

Qdrant is the semantic memory of Synedrix OS and sits at Layer 7 (Memory & Data Layer) of the twelve-layer taxonomy. It is required in all three deployment modes.

flowchart LR
  n1([Qdrant]):::term
  subgraph What it owns
    n2[Semantic retrieval collections]:::agent
    n3[Similarity search]:::agent
    n4[Metadata-aware filtered vector queries]:::agent
    n5[Pattern recall]:::agent
  end
  n1 --> n2
  subgraph What it does not own
    n6[Canonical relational truth]:::warn
    n7[Supabase PG17]:::term
    n6 --> n7
    n8[Explicit relationships]:::warn
    n9[Neo4j]:::term
    n8 --> n9
    n10[Temporal truth]:::warn
    n11[QuestDB]:::term
    n10 --> n11
    n12[Ephemeral hot state]:::warn
    n13[Redis]:::term
    n12 --> n13
    n14[Producing the embeddings themselves]:::warn
    n15[Ollama / vLLM]:::term
    n14 --> n15
  end
  n1 --> n6
  subgraph Why Qdrant
    n16[Filtering happens inside the search]:::term
    n17[No external dependency by default]:::term
    n18[Snapshots are a file-level unit]:::term
  end
  n1 --> n16

What it owns link

Per Tech Stack §8, Qdrant owns:

• Semantic retrieval collections
• Similarity search
• Metadata-aware filtered vector queries
• Pattern recall

Its access pattern is async write/query, its latency profile is low-latency, and the Layered Truth Summary assigns it exactly one truth class: semantic / similarity. That single-line assignment is the whole boundary — everything below follows from it.

Worked example — the live synedrix_os_kb collection link

Synedrix OS has one Qdrant consumer already running in production, which makes the abstraction concrete. os-agt-009, the General Chat Agent, answers natural-language questions about Synedrix OS on the public website by retrieving grounded context from a semantic knowledge base and composing a cited response. Its registry entry constrains it tightly:

Three properties of this deployment generalise to any Synedrix OS use of Qdrant. Retrieval is read-only and carries no execution authority. The collection is dedicated to one consumer rather than shared by convention. And the answer cites its sources, so a retrieved chunk stays traceable to the document it came from.

The agent’s implementation lives in the synedrix-os-website repository, not here; this repository is documentation-only, and the deployment document above — not any code file — is the source of truth for how that agent is deployed and governed.

Semantic memory as a governed scope link

Semantic memory is a declared field on every agent in Agent Registry, not an ambient capability. Across the OS agents that hold it today, the scope is uniformly read:

No OS agent holds semantic-memory write authority in the current registry. Population of collections is an ingest concern, governed by the workflow that performs it, not a capability agents acquire by default. Any domain-pack agent granted write access to a collection is making a governance claim and should declare it as such.

What it does not own link

The Layered Truth Summary in Tech Stack separates truth classes precisely so that no store is asked a question it cannot answer honestly:

The non-overlap is worth stating directly, because it is the boundary most easily eroded in practice:

• Qdrant answers “what is similar to this?” A result is a ranked candidate with a similarity score. It is a retrieval hypothesis, never a fact.
• Neo4j answers “what is connected to what, and how?” An edge is asserted, directional and typed. Similarity is not a relationship; two documents that embed near each other have no lineage between them.
• Supabase answers “what is true right now?” It is the canonical relational store, and it is the only one of the three whose answer an agent may act on as authoritative.

Practically: a retrieved payload is a pointer to a source, not the source. Anything an agent intends to act on must be resolved against Supabase or Neo4j before it becomes a decision. Storing canonical values in a Qdrant payload and reading them back as truth collapses the layered-truth separation and is the failure mode this boundary exists to prevent.

Embeddings are a model call — and that constrains Mode 3 link

Qdrant stores vectors; it does not produce them. Every write and every query is therefore preceded by an inference call to an embedding model, which puts a model dependency on both the ingest path and the retrieval path.

In Mode 3 (air-gapped) this is not optional detail. Per Deployment Model Spec, no external network dependency is permitted, so the embedding model must be served locally by Ollama or vLLM, which Tech Stack §12 makes the only inference layer in that mode. A hosted embedding API would break the mode outright, and would sit badly with Principle 11 (Open by default, sovereign by design) in Modes 1 and 2 as well. The live deployment already meets this bar: nomic-embed-text served by a local Ollama.

A corollary follows. The embedding model is part of a collection’s contract. Changing it changes both the dimensionality and the geometry of the vector space, invalidating every vector already stored. The safe path is to build a new collection with the new model and cut over, not to mutate an existing one in place — which is also why the deployment document insists each consumer own its own collection.

How it is operated link

Ports. Qdrant’s documentation states that “each Qdrant instance requires three open ports: 6333 - For the HTTP API, for the Monitoring health and metrics endpoints 6334 - For the gRPC API 6335 - For Distributed deployment”. The reference deployment exposes 6333.

Observability. Because health and metrics endpoints are served on the HTTP port, Qdrant’s operational health is scrapeable into the Layer 10 monitoring platform alongside every other service. That is infrastructure health only. Retrieval quality is a separate, agent-level concern owned by Observability Metrics Spec §7.1, whose canonical metrics — retrieval_precision_at_k, retrieval_recall_at_k, retrieval_f1_at_k, retrieval_quality_score — are emitted per invocation as os.invocation.retrieval_evaluated events (§9.1) and correlate to a Langfuse trace by trace_id. A healthy Qdrant process and a well-performing retrieval step are two different measurements, and only the second one tells you whether an agent’s answers are grounded.

Security. Qdrant’s own documentation is blunt about the default: “By default, all self-deployed Qdrant instances are not secure. They are open to all network interfaces and do not have any kind of authentication configured.” Three authentication tiers are documented — an admin API key, a read-only API key restricting operations to queries, and JWT-based granular access (jwt_rbac: true) with per-collection r / rw permissions and token expiry. TLS is supported but must be configured; sending an API key over an unencrypted channel is called out as insecure.

The read-only API key maps directly onto the registry’s Semantic memory: read-only declarations, and JWT per-collection permissions map onto the one-collection-per-consumer rule. Those are the enforcement mechanisms for scopes the registry currently only declares. This gap is already recorded: the shared qdrant-core instance the chat agent reads from “has no authentication configured in core-compose.yml today”, noted as a reviewable follow-up in DGX Vercel Chat Agent Deployment §10.

Backup. Collection snapshots are the portable backup and migration unit. Full-storage snapshots are single-node only, so any future move to distributed mode changes the backup strategy rather than merely scaling it.

Memory footprint. Quantization is the tuning lever when self-hosted hardware is fixed — scalar for a 4x reduction at low accuracy cost, binary or product when memory pressure outweighs precision. It is a deployment-time decision per collection, not an OS-level default.

The single vector substrate link

Qdrant is the only vector store at Layer 7. That is a rule in the Memory Fabric Spec, not a current fact that might drift: four memory tiers — episodic, semantic, procedural and profile — are indexed here, and no second vector store is admitted.

The rule earned its keeping in ADR-OS-002. EverOS, the most complete open-source agent-memory runtime available, was rejected from the canonical stack largely because its retrieval layer is LanceDB — a second vector store, duplicating this one. NAMS, adopted as a library over Neo4j, ships its own vector index too; it is scoped to entity resolution inside the graph tier so that it never becomes a general retrieval path.

Two things follow for how collections are laid out:

• One collection per tier, with scope, confidence, validity interval and compliance labels carried in the payload rather than encoded in collection names. Normative collection names, KB consumer-class split, required payload fields, and point-id = memory_id are in Memory Runtime Integration Guide §2.3. Filtered HNSW is what makes this work — the filters that enforce recall scope are the same filters that narrow the candidate set.
• Domain-owned operational collections are a separate class. A domain pack’s derived similarity index (for example a regime-fingerprint or scenario-vector collection) is not a memory tier. It is named ops_<domain-pack-id>_<store>, keyed on the pack’s own domain key rather than memory_id, filtered by tenant_id on every query, given collection-scoped credentials, and rebuilt from the source the pack declares, not from memory_records. See Memory Fabric Spec §3.6 and Memory Runtime Integration Guide §2.3.
• Tier points are projections, never truth. The record of truth is memory_records in Supabase. Wiping every tier collection and rebuilding from Postgres must produce identical behaviour, and that is worth running as an actual test rather than assuming.

Scope resolution happens before the query is built. The Memory Access Broker (os-agt-012) intersects the request scope with the requesting agent’s memory_profile.recall_scope and pushes the result down as payload filters. Retrieving broadly and filtering afterwards is non-compliant, because out-of-scope memory that has already entered the process has already leaked — and it is also worse retrieval. Beyond the Needle’s Illusion shows that semantic interference, not context length, is what degrades evidence access; narrowing the candidate set before ranking is the highest-leverage retrieval decision available, and it happens to be the same seam as authorization.

Why Qdrant link

• Filtering happens inside the search. Layer 7 is asked for “metadata-aware filtered vector queries”, and filterable HNSW is a real answer to that rather than a wrapper around pre- or post-filtering. Tenant scoping, document-class restriction and time windows become filters instead of separate collections.
• Apache 2.0, and self-hostable as a single binary or container. Modes 2 and 3 require the whole platform to run locally with no licence gate. Qdrant clears that without qualification — unlike several other rows in the stack.
• No external dependency by default. A self-hosted instance talks to nothing but its callers, which is what air-gapped Mode 3 needs.
• Named and sparse vectors keep hybrid retrieval a configuration change. Adding lexical matching or a second representation to an existing collection design does not require a second platform at Layer 7.
• Quantization makes memory a tuning decision, not a re-architecture. On fixed self-hosted hardware, a documented 4x to 64x compression range is the difference between a collection fitting and not.
• Snapshots are a file-level unit. A tar archive of a collection is something an operator can move, archive and restore without a bespoke export pipeline — which matters when the deployment target may be an isolated environment.

Deployment and licensing link

Self-hosting. Documented deployment paths are Docker and Docker Compose, Kubernetes via the community Helm chart or the Qdrant Kubernetes Operator, and building from source with Cargo. Qdrant Cloud is the managed option; a Python-only local mode exists for prototyping, and its documentation warns that its data format is not compatible with the server and that it must not be used for production or benchmarking. Only the self-hosted container and Kubernetes paths are relevant to Synedrix OS deployment modes.

Licence — verified. Qdrant is licensed under the Apache License, Version 2.0 (“Apache License, Version 2.0, January 2004”), confirmed against LICENSE in the official qdrant/qdrant repository. This matches Tech Stack §8 (“Qdrant is open source under Apache 2.0”) and the platform table in Deployment Model Spec. No correction to the canonical documents is required, and there is no licensing constraint on delivering Synedrix OS as a product.

One qualification on “self-hostable”. Being self-hostable is not the same as being production-ready out of the box: the official security guidance states that self-hosted open-source deployments are not secure by default and not production-ready until authentication and TLS are configured. That is an operational obligation on every Synedrix OS deployment mode, not a licensing or availability caveat.

Official documentation link

• Qdrant documentation home
• Vector search overview — what vector search is and why payload indexes matter
• Collections — collection definition, distance metrics, named and sparse vectors
• Points — point structure, ID types, vector variants
• Payload — payload definition and supported field types
• Filtering — filter clauses and condition types
• Indexing — HNSW, payload indexes, filterable HNSW
• Hybrid queries — Query API, prefetch, RRF and DBSF fusion
• Quantization — scalar, binary and product quantization
• Snapshots — backup, replication and migration
• Installation — deployment options and required ports
• Security — API keys, read-only keys, JWT RBAC, TLS
• Qdrant LICENSE — Apache License 2.0

Related Synedrix OS documents link

• Memory Fabric Spec — The four tiers indexed here, and the rule that Qdrant is the single vector substrate.
• Synedrix OS Tech Stack — normative platform responsibilities; §8 covers Qdrant, and the Layered Truth Summary sets the semantic/similarity boundary.
• DGX Vercel Chat Agent Deployment — the live synedrix_os_kb deployment, its Qdrant configuration, and the unauthenticated-instance limitation.
• Agent Registry — os-agt-009’s authority boundary, and every OS agent’s declared semantic-memory scope.
• Layer Taxonomy Table — Layer 7 definition and platform mapping.
• Observability Metrics Spec — §7.1 retrieval quality metrics and §9.1 the retrieval evaluation event.
• Deployment Model Spec — the three modes, and Mode 3’s prohibition on external network dependencies.
• Core Principles — Principle 11 (Open by default, sovereign by design), which the local-embedding requirement follows from.

Synedrix OS · Platform reference · Qdrant