feat: add Qdrant vector storage integration (M9 Phase 1) (#63)

* feat: add Qdrant vector storage integration (M9 Phase 1)

Implements vector storage and similarity search via Qdrant for M9: Semantic Memory.

Core Changes:
- New QdrantStore module with store/search/has_embedding methods
- SQLite embeddings_metadata table with foreign key constraints
- PRAGMA foreign_keys enabled via SqliteConnectOptions
- Docker Compose Qdrant service on ports 6333/6334

Breaking Changes (pre-1.0):
- SqliteStore::save_message() returns Result<i64> for message_id
- QdrantStore::store() requires model parameter
- ENV_KEYS replaces LLM_ENV_KEYS constant

Tests:
- 12 new tests (3 unit + 2 integration + 1 CASCADE DELETE + 3 config)
- 98% coverage for new code
- All checks pass: fmt, clippy, nextest

Closes #60

* ci: allow thiserror 1.x/2.x duplicate for qdrant-client compat

* chore: update Qdrant Docker image to v1.16.3

* feat(test): add testcontainers for Qdrant integration tests

Add testcontainers-rs 0.27 for automated Qdrant container lifecycle in
integration tests. Replace ignored tests with testcontainers-powered
equivalents that run in CI.

Changes:
- Add testcontainers 0.27 workspace dependency (MIT/Apache-2.0, dev-only)
- Create crates/zeph-memory/tests/qdrant_integration.rs with:
  - Custom GenericImage for qdrant/qdrant:v1.13.6
  - setup_with_qdrant() helper with WaitFor::message_on_stdout
  - 3 tests: ensure_collection_is_idempotent, store_and_search_vector,
    search_with_conversation_filter
- Remove 2 #[ignore] tests from qdrant.rs (moved to integration tests)
- Add integration job to CI workflow (ubuntu-latest, Docker required)
- Document testcontainers usage in CONTRIBUTING.md

All 153 tests pass (6 skipped Ollama/Claude tests require external services).

* fix: correct import order and formatting in qdrant_integration.rs

* feat(test): add nextest profiles and fix CI test separation

Add nextest configuration to properly separate unit tests from integration
tests in CI. Fix macOS test failures by excluding testcontainers integration
tests from the main test job.

Changes:
- Create .config/nextest.toml with default and ci profiles
- Update CI test job to run only unit tests: --lib --bins (excludes tests/)
- Update CI integration job to use --profile ci for explicit inclusion
- Update CONTRIBUTING.md with nextest commands and test separation docs

Test separation:
- test job: Unit tests only (--lib --bins), runs on ubuntu + macos
- integration job: Integration tests with testcontainers, ubuntu-latest only
- coverage job: All tests for coverage metrics

Fixes: macOS test failures due to Docker socket not available
  Error: SocketNotFoundError("/var/run/docker.sock")
  Solution: Integration tests now run only in dedicated integration job

Author: bug-ops

.config/nextest.toml

@@ -0,0 +1,17 @@
+# Nextest configuration for zeph project
+# https://nexte.st/book/configuration.html
+
+[profile.default]
+# Default profile for local development
+# No default filter - run all unit tests
+# Integration tests are in separate test binaries (tests/*_integration.rs)
+# and can be run explicitly with --test flag or using the ci profile
+
+[profile.ci]
+# CI profile that runs ALL tests including integration tests
+# Override with: cargo nextest run --profile ci
+default-filter = "all()"
+
+[profile.ci.junit]
+# Store JUnit XML report for CI
+path = "target/nextest/ci/junit.xml"

.github/workflows/ci.yml

@@ -71,7 +71,27 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       - uses: mozilla-actions/[email protected]
       - name: Run tests
-        run: cargo nextest run --workspace
+        run: cargo nextest run --workspace --lib --bins
+        env:
+          RUSTC_WRAPPER: sccache
+          SCCACHE_GHA_ENABLED: "true"
+
+  integration:
+    name: Integration Tests
+    needs: [lint-fmt, lint-clippy]
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v6
+      - uses: moonrepo/setup-rust@v1
+        with:
+          bins: cargo-nextest
+          cache-target: release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - uses: mozilla-actions/[email protected]
+      - name: Run integration tests (testcontainers)
+        run: cargo nextest run --workspace --profile ci --test '*integration*'
         env:
           RUSTC_WRAPPER: sccache
           SCCACHE_GHA_ENABLED: "true"

CHANGELOG.md

@@ -8,6 +8,22 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Added
 
+#### M9 Phase 1: Qdrant Integration (Issue #60)
+- New `QdrantStore` module in zeph-memory for vector storage and similarity search
+- `QdrantStore::store()` persists embeddings to Qdrant and tracks metadata in SQLite
+- `QdrantStore::search()` performs cosine similarity search with filtering by conversation_id and role
+- `QdrantStore::has_embedding()` checks if message has associated embedding
+- `QdrantStore::ensure_collection()` idempotently creates Qdrant collection with 768-dimensional vectors
+- SQLite migration `002_embeddings_metadata.sql` for embedding metadata tracking
+- `embeddings_metadata` table with foreign key constraint to messages (ON DELETE CASCADE)
+- PRAGMA foreign_keys enabled in SqliteStore via SqliteConnectOptions
+- `SearchFilter` and `SearchResult` types for flexible query construction
+- `MemoryConfig.qdrant_url` field with `ZEPH_QDRANT_URL` environment variable override (default: http://localhost:6334)
+- Docker Compose Qdrant service (qdrant/qdrant:v1.13.6) on ports 6333/6334 with persistent storage
+- Integration tests for Qdrant operations (ignored by default, require running Qdrant instance)
+- Unit tests for SQLite metadata operations with 98% coverage
+- 12 new tests total (3 unit + 2 integration for QdrantStore, 1 CASCADE DELETE test for SqliteStore, 3 config tests)
+
 #### M8: Embeddings support (Issue #54)
 - `LlmProvider` trait extended with `embed(&str) -> Result<Vec<f32>>` for generating text embeddings
 - `LlmProvider` trait extended with `supports_embeddings() -> bool` for capability detection
@@ -22,6 +38,22 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - Docker Compose configuration: added `ZEPH_LLM_EMBEDDING_MODEL` environment variable
 
 ### Changed
+
+**BREAKING CHANGES** (pre-1.0.0):
+- `SqliteStore::save_message()` now returns `Result<i64>` instead of `Result<()>` to enable embedding workflow
+- `SqliteStore::new()` uses `sqlx::migrate!()` macro instead of INIT_SQL constant for proper migration management
+- `QdrantStore::store()` requires `model: &str` parameter for multi-model support
+- Config constant `LLM_ENV_KEYS` renamed to `ENV_KEYS` to reflect inclusion of non-LLM variables
+
+**Migration:**
+```rust
+// Before:
+let _ = store.save_message(conv_id, "user", "hello").await?;
+
+// After:
+let message_id = store.save_message(conv_id, "user", "hello").await?;
+```
+
 - `OllamaProvider::new()` now accepts `embedding_model` parameter (breaking change, pre-v1.0)
 - Config schema: added `llm.embedding_model` field with serde default for backward compatibility
 

CONTRIBUTING.md

@@ -20,9 +20,36 @@ cargo build
 ### Test
 
 ```bash
-cargo nextest run
+# Run unit tests only (exclude integration tests)
+cargo nextest run --workspace --lib --bins
+
+# Run all tests including integration tests (requires Docker)
+cargo nextest run --workspace --profile ci
 ```
 
+**Nextest profiles** (`.config/nextest.toml`):
+- `default`: Runs all tests (unit + integration)
+- `ci`: CI environment, runs all tests with JUnit XML output for reporting
+
+### Integration Tests
+
+Integration tests use [testcontainers-rs](https://github.com/testcontainers/testcontainers-rs) to automatically spin up Docker containers for external services (Qdrant, etc.).
+
+**Prerequisites:** Docker must be running on your machine.
+
+```bash
+# Run only integration tests
+cargo nextest run --workspace --test '*integration*'
+
+# Run unit tests only (skip integration tests)
+cargo nextest run --workspace --lib --bins
+
+# Run all tests
+cargo nextest run --workspace
+```
+
+Integration test files are located in each crate's `tests/` directory and follow the `*_integration.rs` naming convention.
+
 ### Lint
 
 ```bash
@@ -43,15 +70,15 @@ cargo llvm-cov --all-features --workspace
 | `zeph-core` | Agent loop, config, channel trait |
 | `zeph-llm` | LlmProvider trait, Ollama + Claude backends |
 | `zeph-skills` | SKILL.md parser, registry, prompt formatter |
-| `zeph-memory` | SQLite conversation persistence |
+| `zeph-memory` | SQLite conversation persistence, Qdrant vector search |
 | `zeph-channels` | Telegram adapter |
 
 ## Pull Requests
 
 1. Create a feature branch: `feat/<scope>/<description>` or `fix/<scope>/<description>`
-2. Keep changes focused — one logical change per PR
+2. Keep changes focused -- one logical change per PR
 3. Add tests for new functionality
-4. Ensure all checks pass: `cargo +nightly fmt`, `cargo clippy`, `cargo nextest run`
+4. Ensure all checks pass: `cargo +nightly fmt`, `cargo clippy`, `cargo nextest run --lib --bins`
 5. Write a clear PR description following the template
 
 ## Commit Messages
@@ -64,7 +91,7 @@ cargo llvm-cov --all-features --workspace
 
 - Follow workspace clippy lints (pedantic enabled)
 - Use `cargo +nightly fmt` for formatting
-- Avoid unnecessary comments — code should be self-explanatory
+- Avoid unnecessary comments -- code should be self-explanatory
 - Comments are only for cognitively complex blocks
 
 ## License