updated documentation for semantic and constant refactor

docs/services/memory-service.md

@@ -17,7 +17,7 @@ stores directly.
 - `better-sqlite3` — SQLite driver
 - `@qdrant/js-client-rest` — Qdrant vector store client
 - `dotenv` — environment variable loading
-- `@nexusai/shared` — shared utilities
+- `@nexusai/shared` — shared utilities and constants
 
 ## Environment Variables
 
@@ -28,18 +28,23 @@ stores directly.
 | QDRANT_URL | No | http://localhost:6333 | Qdrant instance URL |
 
 ## Internal Structure
+
+```
 src/
 ├── db/
 │   ├── index.js       # SQLite connection + initialization
 │   └── schema.js      # Table definitions, indexes, FTS5, triggers
 ├── episodic/
-│   └── index.js       # Session + episode CRUD
-├── semantic/          # Qdrant vector operations (in progress)
+│   └── index.js       # Session + episode CRUD and FTS search
+├── semantic/
+│   └── index.js       # Qdrant collection management, upsert, search, delete
 ├── entities/          # Entity + relationship CRUD (upcoming)
 └── index.js           # Express app + route definitions
+```
 
 ## SQLite Schema
-Four core tables:
+
+Five core tables:
 
 - **sessions** — top-level conversation containers, identified by an `external_id`
 - **episodes** — individual exchanges (user message + AI response) tied to a session
@@ -59,6 +64,42 @@ keep the FTS index automatically in sync with the episodes table.
 - `foreign_keys = ON` — enforces referential integrity and cascade deletes
 - PRAGMAs are set via `db.pragma()` separately from `db.exec()`
 
+## Qdrant / Semantic Layer
+
+Three collections are initialized on service startup (created if they don't already exist):
+
+| Collection | Purpose |
+|---|---|
+| `episodes` | Embeddings for individual conversation exchanges |
+| `entities` | Embeddings for named entities |
+| `summaries` | Embeddings for condensed episode summaries |
+
+All collections use **768-dimension vectors** with **Cosine similarity**, matching the
+output of the `nomic-embed-text` embedding model via Ollama.
+
+Vector dimension and distance metric are defined in `@nexusai/shared` constants
+(`QDRANT.VECTOR_SIZE`, `QDRANT.DISTANCE_METRIC`) — not hardcoded in this service.
+
+### Semantic Layer Operations
+
+Each collection exposes three operations via helper functions in `src/semantic/index.js`:
+
+- **Upsert** — stores a vector with a payload containing the SQLite row ID, enabling
+  lookups back to the full content after a vector search
+- **Search** — returns the top-k most similar vectors, with optional Qdrant filter
+- **Delete** — removes a vector point by ID
+
+The `wait: true` flag is used on all write operations so the caller receives confirmation
+only after Qdrant has committed the change.
+
+### Hybrid Retrieval Pattern
+
+Qdrant and SQLite work as a pair — neither operates in isolation:
+
+1. Query is embedded and searched in Qdrant → returns IDs + similarity scores
+2. IDs are used to fetch full content from SQLite
+3. Results are ranked and assembled into a context package
+
 ## Endpoints
 
 ### Health
@@ -105,12 +146,4 @@ keep the FTS index automatically in sync with the episodes table.
 }
 ```
 
-> Semantic (Qdrant) and entity endpoints will be documented as they are built out.
-
-## Endpoints
-
-| Method | Path | Description |
-|---|---|---|
-| GET | /health | Service health check |
-
-> Further endpoints will be documented as the service is built out.
+> Semantic (Qdrant) and entity REST endpoints will be documented as they are built out.