Memory Engine Semantic Memory

Document ID: MEM-006
File Path: docs/06-memory-engine/semantic-memory.md
Version: 1.0.0
Status: Draft
Owner: AI Platform Team
Last Updated: 2026-06-27

1. Purpose

This document specifies semantic memory in the Memory Engine: how factual, durable knowledge is embedded, stored, and retrieved by meaning rather than by exact wording.

Semantic memory is the platform’s knowledge layer — product docs, APIs, policies, standards, and learned facts — distinct from conversational or episodic memory (see Memory System §11).

2. What Belongs in Semantic Memory

Good fit	Poor fit
Policies, standards, documentation	Live conversation turns
API specs, schemas	Per-execution scratch state
Reusable facts and definitions	Highly volatile data
Distilled lessons (“X causes Y”)	Raw, unprocessed logs

Semantic memories are typically permanent and non-decaying (see Ranking §4).

3. Embeddings

Semantic memory is searchable because each record carries a vector embedding.

Embeddings are generated by the LLM Gateway, so the Engine never calls a provider directly.
The embedding model and dimension are pinned per collection; mixing models in one collection is forbidden (distances would be meaningless).
Embedding model identity and version are stored with the record for reproducibility and reindexing.

Supported embedding providers follow the Memory System §15 list (OpenAI, Gemini, VoyageAI, Cohere, Ollama, local models).

4. Chunking

Long content is split into retrievable chunks before embedding:

Document
  │  chunker (semantic / fixed / heading-aware)
  ▼
Chunks ─► embed each ─► store as linked child memories

Strategy	When
Heading-aware	Structured docs (markdown, specs)
Semantic	Prose where topic boundaries matter
Fixed-window + overlap	Uniform text, fallback

Chunks link back to a parent memory id so retrieval can return either the precise chunk or the whole document. Overlap (default ~15%) preserves context across boundaries.

5. Storage Layout

Vector + payload live in a per-tenant Qdrant collection (see Storage §5).
Canonical content + metadata live in PostgreSQL.
Parent/child chunk relationships are recorded in PostgreSQL and (optionally) the knowledge graph.

6. Retrieval

Semantic memory is the primary target of the vector and hybrid retrieval strategies. A query is embedded with the same model as the collection, then nearest neighbors are fetched with payload filters applied inside Qdrant. Chunk hits may be expanded to their parent document when the caller needs full context.

7. Deduplication & Canonicalization

To prevent the knowledge layer from filling with near-identical facts:

On write, the Engine checks for high-similarity existing memories (cosine ≥ threshold). A near-duplicate becomes a new version of, or a reference to, the canonical record rather than a separate entry.
Conflicting facts (same subject, different claim) are flagged for review and may carry a confidence label used in Ranking §2.

8. Freshness & Reembedding

Semantic facts do not decay by time but can be superseded; updating content creates a new version and re-embeds.
Changing the embedding model triggers a controlled reindex (dual-write old and new collections, atomic swap) per Storage §9.

9. Quality Controls

Control	Purpose
Source attribution (`labels.source`)	Trust + auditability
Confidence scoring	Down-rank uncertain facts
Verification flag	Mark human-reviewed knowledge
Conflict detection	Surface contradictory facts

These feed both ranking and governance.

10. Security

Semantic memory respects the same scopes and policies as all memory. Knowledge shared at organization or public scope is still subject to per-principal ABAC (e.g. region or clearance) at query time. See Overview §12.

11. Non-Functional Requirements

Requirement	Target
Semantic search (warm)	< 25 ms p95
Chunk + embed throughput	embedding-bound (Gateway)
Dedup check on write	< 20 ms p95

12. Dependencies

14. Revision History

Version	Date	Description
1.0.0	2026-06-27	Initial Memory Engine Semantic Memory specification