From 45a00e32dec506a20da07ff44b2dd244a214d68e Mon Sep 17 00:00:00 2001
From: Storme-bit <tk.stomre@gmail.com>
Date: Sun, 5 Apr 2026 00:26:58 -0700
Subject: [PATCH] updated memory service documentation

---
 docs/services/memory-service.md | 27 ++++++++++++++++++++++++---
 1 file changed, 24 insertions(+), 3 deletions(-)

diff --git a/docs/services/memory-service.md b/docs/services/memory-service.md
index 37ebde5..c1f152b 100644
--- a/docs/services/memory-service.md
+++ b/docs/services/memory-service.md
@@ -9,7 +9,8 @@
 
 Responsible for all reading and writing of long-term memory. Acts as the
 sole interface to both SQLite and Qdrant — no other service accesses these
-stores directly.
+stores directly. On episode creation, automatically calls the embedding
+service to generate and store a vector in Qdrant.
 
 ## Dependencies
 
@@ -26,6 +27,7 @@ stores directly.
 | PORT | No | 3002 | Port to listen on |
 | SQLITE_PATH | Yes | — | Path to SQLite database file |
 | QDRANT_URL | No | http://localhost:6333 | Qdrant instance URL |
+| EMBEDDING_SERVICE_URL | No | http://localhost:3003 | Embedding service URL |
 
 ## Internal Structure
 
@@ -35,7 +37,7 @@ src/
 │   ├── index.js       # SQLite connection + initialization
 │   └── schema.js      # Table definitions, indexes, FTS5, triggers
 ├── episodic/
-│   └── index.js       # Session + episode CRUD and FTS search
+│   └── index.js       # Session + episode CRUD, FTS search, embedding write path
 ├── semantic/
 │   └── index.js       # Qdrant collection management, upsert, search, delete
 ├── entities/
@@ -93,6 +95,25 @@ Each collection exposes three operations via helper functions in `src/semantic/i
 The `wait: true` flag is used on all write operations so the caller receives confirmation
 only after Qdrant has committed the change.
 
+## Embedding Write Path
+
+When a new episode is created, the memory service automatically generates and stores
+a vector embedding in Qdrant via the embedding service:
+
+1. Episode is saved to SQLite synchronously — the response is returned immediately
+2. Both sides of the exchange are combined into a single text:
+   ```
+   User: {userMessage}
+   Assistant: {aiResponse}
+   ```
+3. This text is sent to the embedding service (`POST /embed`)
+4. The returned vector is upserted into the `episodes` Qdrant collection with a
+   payload of `{ sessionId, createdAt }` for filtering and lookups
+
+The embedding step is **fire-and-forget** — it runs asynchronously after the SQLite
+insert succeeds. If embedding fails, the episode is still saved and searchable via
+FTS. The error is logged but does not affect the API response.
+
 ### Hybrid Retrieval Pattern
 
 Qdrant and SQLite work as a pair — neither operates in isolation:
@@ -139,7 +160,7 @@ Entities and relationships are stored in SQLite with two key constraints:
 
 | Method | Path | Description |
 |---|---|---|
-| POST | /episodes | Create a new episode |
+| POST | /episodes | Create episode + auto-embed into Qdrant |
 | GET | /episodes/search?q=&limit= | Full-text search across episodes |
 | GET | /episodes/:id | Get episode by ID |
 | GET | /sessions/:id/episodes?limit=&offset= | Get paginated episodes for a session |