From 8a52791630d171fae62c563bc65c9d9666c38f20 Mon Sep 17 00:00:00 2001
From: Storme-bit <tk.stomre@gmail.com>
Date: Sat, 4 Apr 2026 07:08:14 -0700
Subject: [PATCH] Updated memory service documentation

---
 docs/services/memory-service.md | 80 +++++++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)

diff --git a/docs/services/memory-service.md b/docs/services/memory-service.md
index be70b82..c201c94 100644
--- a/docs/services/memory-service.md
+++ b/docs/services/memory-service.md
@@ -27,6 +27,86 @@ stores directly.
 | SQLITE_PATH | Yes | — | Path to SQLite database file |
 | 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)
+├── entities/          # Entity + relationship CRUD (upcoming)
+└── index.js           # Express app + route definitions
+
+## SQLite Schema
+Four core tables:
+
+- **sessions** — top-level conversation containers, identified by an `external_id`
+- **episodes** — individual exchanges (user message + AI response) tied to a session
+- **entities** — named things the system learns about (people, places, concepts)
+- **relationships** — directional labeled links between entities
+- **summaries** — condensed episode groups for efficient context retrieval
+
+### FTS5 Full-Text Search
+
+An `episodes_fts` virtual table enables keyword search across all episodes.
+Three triggers (`episodes_fts_insert`, `episodes_fts_update`, `episodes_fts_delete`)
+keep the FTS index automatically in sync with the episodes table.
+
+### SQLite Configuration
+
+- `journal_mode = WAL` — non-blocking reads during writes
+- `foreign_keys = ON` — enforces referential integrity and cascade deletes
+- PRAGMAs are set via `db.pragma()` separately from `db.exec()`
+
+## Endpoints
+
+### Health
+
+| Method | Path | Description |
+|---|---|---|
+| GET | /health | Service health check |
+
+### Sessions
+
+| Method | Path | Description |
+|---|---|---|
+| POST | /sessions | Create a new session |
+| GET | /sessions/:id | Get session by internal ID |
+| GET | /sessions/by-external/:externalId | Get session by external ID |
+| DELETE | /sessions/:id | Delete session (cascades to episodes + summaries) |
+
+**POST /sessions body:**
+```json
+{
+  "externalId": "unique-session-id",
+  "metadata": {}
+}
+```
+
+### Episodes
+
+| Method | Path | Description |
+|---|---|---|
+| POST | /episodes | Create a new episode |
+| GET | /episodes/search?q=&limit= | Full-text search across episodes |
+| GET | /episodes/:id | Get episode by ID |
+| GET | /sessions/:id/episodes?limit=&offset= | Get episodes for a session |
+| DELETE | /episodes/:id | Delete an episode |
+
+**POST /episodes body:**
+```json
+{
+  "sessionId": 1,
+  "userMessage": "Hello",
+  "aiResponse": "Hi there!",
+  "tokenCount": 10,
+  "metadata": {}
+}
+```
+
+> Semantic (Qdrant) and entity endpoints will be documented as they are built out.
+
 ## Endpoints
 
 | Method | Path | Description |