Gateway Module — `memory/`

1. Purpose

The persistent-memory tier of the Lisa Memory Gateway. It owns three durable document types — preference, knowledge, summary — stored in SQLite with Voyage-AI embeddings for semantic recall and an FTS5 sidecar for keyword recall. It also owns the shared database substrate: memory/db.ts (1,258 lines) is the single schema-owning module for the entire gateway — every other module's tables, virtual tables, triggers, and migrations are declared here, not in the consuming module. The module exposes an EmbeddingProvider (Voyage → keyword fallback, resilient wrapper) that psychic-cache, context, and vault-index all consume for their own embeddings.

Architectural note (code-vs-doc): the module's REST surface is not defined inside memory/. The memory/index.ts barrel is a factory (createMemoryLayer) plus a background-embedding helper — it exports no Express router. The /api/health, /api/health/detail, and GET/POST/PUT/DELETE /api/memory[/:id] endpoints are declared inline in the top-level server/index.ts (≈ lines 531–731), wired directly against memory.memoryRepo / memory.embeddingRepo. This is the one gateway module whose HTTP surface lives outside its own folder.

2. File Inventory

3. Public API Surface

REST Endpoints

All routes declared inline in server/index.ts. Auth posture per AK-415/435/436: /api/health is the only public GET (liveness only); every other GET requires a Bearer; every mutation requires the write Bearer only.

POST /api/memory/search was removed (D27) — sole consumer of the deleted createContextRetrievalService. Canonical retrieval is now POST /api/context/assemble.

MCP Tools

Consumed via the persistent-memory dual-write path.

4. Internal API

Exported for cross-module use:

• openDatabase(): Database — the shared handle every module's factory receives (db.ts).
• createMemoryLayer(config): MemoryLayer — {embeddingProvider, embeddingRepo, memoryRepo, close()}.
• scheduleExchangeEmbedding(layer, opts) — fire-and-forget knowledge-doc embedding of a chat exchange (skips < minTokens, default 50).
• createVoyageProvider / createKeywordFallbackProvider / createResilientProvider + ResilientProviderHooks, VoyageAuthError — imported by server/index.ts for the degraded-alert wiring.
• createMemoryRepository / createEmbeddingRepository — consumed by context adapters.
• Type re-exports: MemoryLayer, MemoryDocument, MemoryContent, EmbeddingProvider, etc. (context, psychic-cache, vault-index all import EmbeddingProvider from here).

5. Background Services

• Async embedding on write — setImmediate after POST/PUT /api/memory and inside scheduleExchangeEmbedding; embedding failure is caught + logged, never blocks the response (FTS row still lands).
• LRU + TTL caches — docCache (max 1,000, 5-min TTL), typeCache (max 200, 2-min TTL). Eviction is lazy (on set/get), no timer. typeCache.clear() on any write for conservative invalidation.
• Resilient provider recovery — onPrimaryRecovered fires on first Voyage success after a failure, clearing the degraded-suppression flag (AK-321/H-07). No timer; edge-triggered.

6. Data Contracts

Read-path content validation (repositories.ts):

• PreferenceContentSchema = {key, value, source, confidence:number}
• KnowledgeContentSchema = {topic, content, sourceSessionIds:string[]=[], lastReferencedAt:string=''}
• SummaryContentSchema = {summary, keyTopics[], decisionsReached[], unresolvedQuestions[]}

Write-path (server/index.ts):

• CreateMemoryInputSchema = {type:enum, content:union(3 above), tokenCount?, userId?, sessionId?}
• UpdateMemoryInputSchema = {content?:union, tokenCount?}

VoyageResponseSchema (embeddings.ts) = {data:[{embedding:number[]}], usage:{total_tokens}}.

Owned tables (declared in db.ts): memory_documents (+4 indexes), conversation_summaries, memory_fts (fts5), vec_embeddings (vec0, 512-dim), schema_meta. Note db.ts also declares every other module's tables.

7. Dependencies

• Gateway modules consumed: shared/search-utils (buildFts5Query). Depended-on-by: psychic-cache, context, vault-index, agent-memory, dispatch, sessions, activity, etc. (all consume openDatabase + EmbeddingProvider).
• External libraries: better-sqlite3, sqlite-vec (vec0 virtual tables), zod, Voyage AI HTTP API (api.voyageai.com/v1/embeddings), Node crypto.
• Environment variables: VOYAGE_API_KEY (credential-store-first: systemd LoadCredential → env fallback; empty → keyword-fallback-only boot), voyageModel (default voyage-3-lite, 512-dim), dbPath (the gateway SQLite datastore).

8. Test Coverage

No dedicated memory/repositories.ts suite; the read/write CRUD is exercised indirectly via context + search + validation suites. Coverage of db.ts migrations is via cross-module suites, not a targeted migration test.

9. Known Limitations

• REST surface lives in server/index.ts, not the module — the one gateway module with no self-contained router. A future refactor should extract a createMemoryRouter for symmetry; until then, changes to memory endpoints require editing the 900+-line root file.
• db.ts is a god-file — 1,258 lines owning every module's schema. High blast radius: any migration bug affects the whole gateway. Accepted for single-DB-handle simplicity, but flagged for the LisaOSMap dependency graph.
• Keyword fallback quality — trigram/unigram hashing produces low-quality vectors; recall degrades (never fails) when Voyage is unreachable.
• No direct-repository unit suite for repositories.ts — CRUD correctness is inferred from consumers.

10. Change History