Feature/qdrant ltm foundation

Makefile

@@ -1,12 +1,12 @@
-.PHONY: help lock install build test test-integration benchmark-ltm-local chroma-up chroma-down check compile docs-serve docs-build
+.PHONY: help lock install build test test-integration benchmark-ltm-local benchmark-ltm-qdrant-local chroma-up chroma-down check compile docs-serve docs-build
 
 # Update poetry.lock
 lock:
 	poetry lock
 
 # Install dependencies (including dev) and download the spaCy model
 install:
-	poetry install --with dev --no-interaction
+	poetry install --with dev --extras qdrant --no-interaction
 	poetry run python -m spacy download en_core_web_sm
 
 # Verify package metadata
@@ -33,6 +33,9 @@ test-integration:
 benchmark-ltm-local:
 	poetry run python -m integrationtest.run_ltm_benchmark
 
+benchmark-ltm-qdrant-local:
+	poetry run python -m integrationtest.run_ltm_benchmark --backend qdrant
+
 # Stop containers without removing persistent volumes
 chroma-down:
 	docker compose -f compose.chroma.yml down
@@ -61,6 +64,7 @@ help:
 	@echo "  make chroma-up             Start Chroma 0.6.3 (Docker container)"
 	@echo "  make test-integration      Run integration tests against the local Chroma server"
 	@echo "  make benchmark-ltm-local   Run the local DMF LTM + Ollama benchmark"
+	@echo "  make benchmark-ltm-qdrant-local Run the local DMF LTM + Ollama benchmark with Qdrant"
 	@echo "  make chroma-down           Stop Chroma containers"
 	@echo "  make build                 Build wheel package in dist/"
 	@echo "  make docs-serve            Start development server for documentation"

README.md

@@ -36,10 +36,31 @@ You can install it via pip:
 pip install dmf-memory
 ```
 
+Install the optional Qdrant backend when you want to use local in-memory
+Qdrant LTM:
+
+```bash
+pip install 'dmf-memory[qdrant]'
+```
+
 ## Configuration
 
 DMF is fully configurable via a [TOML](https://toml.io/en/) file. You can adjust NLP models, temporal decay rates, and pruning priorities to suit your agent's needs.
 
+Minimal Qdrant Local Mode configuration:
+
+```toml
+[ltm]
+enabled = true
+storage_type = "qdrant"
+qdrant_mode = "memory"
+```
+
+Qdrant Local Mode uses `QdrantClient(":memory:")`: each client has separate
+state, and all archived data disappears when the process exits. Persistent
+local Qdrant and Qdrant server connections are outside the current release
+scope.
+
 For a comprehensive guide on all configuration parameters, please check our [configuration documentation](configuration.md) in MkDocs.
 
 ## Development & Makefile

dmf/__init__.py

@@ -23,7 +23,7 @@
 """Deterministic Memory Framework package."""
 
 from dmf.analysis import EmbeddingEngine, InteractionMatrix, NLPEngine, ScoringEngine
-from dmf.memory import ChromaLTMHook, FileLTMHook, Memory, TemporalMemory
+from dmf.memory import ChromaLTMHook, FileLTMHook, Memory, QdrantLTMHook, TemporalMemory
 from dmf.models import AnalysisReport
 from dmf.runtime import InteractionPipeline
 
@@ -41,6 +41,7 @@
     "InteractionPipeline",
     "Memory",
     "NLPEngine",
+    "QdrantLTMHook",
     "ScoringEngine",
     "TemporalMemory",
 ]

dmf/memory/__init__.py

@@ -50,7 +50,7 @@
     expand_card_evidence,
     render_evidence_context,
 )
-from dmf.memory.ltm_hooks import ChromaLTMHook, FileLTMHook
+from dmf.memory.ltm_hooks import ChromaLTMHook, FileLTMHook, QdrantLTMHook
 from dmf.memory.query_understanding import QueryUnderstandingParser, parse_query_frame
 from dmf.memory.temporal_memory import TemporalMemory
 
@@ -79,6 +79,7 @@
     "expand_card_evidence",
     "render_evidence_context",
     "FileLTMHook",
+    "QdrantLTMHook",
     "QueryUnderstandingParser",
     "TemporalMemory",
     "parse_query_frame",

dmf/memory/candidate_generation.py

@@ -53,7 +53,7 @@
     QUERY_CURRENTNESS_HISTORICAL,
     QUERY_CURRENTNESS_MIXED,
 )
-from dmf.models.ltm_hook import LTMHook
+from dmf.models.ltm_hook import CardSearchLTMHook, LTMHook
 from dmf.models.memory import MemoryCard, QueryFrame, RetrievedEvidence
 from dmf.models.raw_ltm import RawLTMRecord, RawRecallHit
 
@@ -215,7 +215,7 @@ def retrieve(
         """
         if (
             self._ltm_hook is not None
-            and hasattr(self._ltm_hook, "search_cards")
+            and isinstance(self._ltm_hook, CardSearchLTMHook)
             and query.query_embedding is not None
         ):
             hits = self._ltm_hook.search_cards(query.query_embedding, k=k)

dmf/memory/ltm_hooks/__init__.py

@@ -24,5 +24,6 @@
 
 from dmf.memory.ltm_hooks.chroma_hook import ChromaLTMHook
 from dmf.memory.ltm_hooks.file_hook import FileLTMHook
+from dmf.memory.ltm_hooks.qdrant_hook import QdrantLTMHook
 
-__all__ = ["ChromaLTMHook", "FileLTMHook"]
+__all__ = ["ChromaLTMHook", "FileLTMHook", "QdrantLTMHook"]

dmf/memory/ltm_hooks/chroma_filters.py

@@ -0,0 +1,75 @@
+# Copyright (c) 2026-present matstech
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+#
+# SPDX-License-Identifier: MIT
+
+"""Translate backend-neutral recall filters to Chroma metadata predicates."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from dmf.models.recall_filter import RecallFilter
+
+FilterTarget = Literal["raw", "card"]
+
+
+def build_chroma_where(
+    recall_filter: RecallFilter | None,
+    *,
+    target: FilterTarget,
+) -> dict[str, Any] | None:
+    """Return a Chroma ``where`` mapping for the target collection, or ``None``."""
+    if recall_filter is None or recall_filter.is_empty:
+        return None
+
+    conditions: list[dict[str, Any]] = []
+    record_field = "record_id" if target == "raw" else "source_record_id"
+    if recall_filter.record_ids:
+        conditions.append({record_field: {"$in": list(recall_filter.record_ids)}})
+    if recall_filter.excluded_record_ids:
+        conditions.append(
+            {record_field: {"$nin": list(recall_filter.excluded_record_ids)}}
+        )
+    if recall_filter.roles:
+        conditions.append({"raw_role": {"$in": list(recall_filter.roles)}})
+    if recall_filter.interaction_id_min is not None:
+        conditions.append(
+            {"raw_interaction_id": {"$gte": recall_filter.interaction_id_min}}
+        )
+    if recall_filter.interaction_id_max is not None:
+        conditions.append(
+            {"raw_interaction_id": {"$lte": recall_filter.interaction_id_max}}
+        )
+    if recall_filter.created_at_min is not None:
+        conditions.append({"raw_created_at": {"$gte": recall_filter.created_at_min}})
+    if recall_filter.created_at_max is not None:
+        conditions.append({"raw_created_at": {"$lte": recall_filter.created_at_max}})
+    if recall_filter.card_kinds:
+        conditions.append({"kind": {"$in": list(recall_filter.card_kinds)}})
+
+    if not conditions:
+        return None
+    if len(conditions) == 1:
+        return conditions[0]
+    return {"$and": conditions}
+
+
+__all__ = ["build_chroma_where"]