116 lines
3.4 KiB
Markdown
116 lines
3.4 KiB
Markdown
# Memory Service
|
|
|
|
**Package:** `@nexusai/memory-service`
|
|
**Location:** `packages/memory-service`
|
|
**Deployed on:** Mini PC 1 (192.168.0.81)
|
|
**Port:** 3002
|
|
|
|
## Purpose
|
|
|
|
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.
|
|
|
|
## Dependencies
|
|
|
|
- `express` — HTTP API
|
|
- `better-sqlite3` — SQLite driver
|
|
- `@qdrant/js-client-rest` — Qdrant vector store client
|
|
- `dotenv` — environment variable loading
|
|
- `@nexusai/shared` — shared utilities
|
|
|
|
## Environment Variables
|
|
|
|
| Variable | Required | Default | Description |
|
|
|---|---|---|---|
|
|
| PORT | No | 3002 | Port to listen on |
|
|
| 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 |
|
|
|---|---|---|
|
|
| GET | /health | Service health check |
|
|
|
|
> Further endpoints will be documented as the service is built out. |