Memory Epic

User Journey

The Memory bounded context provides semantic memory capabilities through vector embeddings for policy documents. It enables similarity-based search beyond keyword matching, allowing policy consumers to find relevant governance rules using natural language queries even when different terminology is used.

Jobs to be Done & EARS Requirements

Job: Store Policy Embeddings

User Story: As a policy administrator, I want to generate and store vector embeddings for policy documents, so that they can be retrieved through semantic search.

EARS Requirement:

• While the system is operational, when a StoreEmbedding command is received with policy document content and identifier, the memory context shall:
  1. Generate 384-dimensional embedding vector using EmbeddingGemma model
  2. Validate embedding dimensions equal exactly 384
  3. Store vector in pgvector with cosine similarity index
  4. Associate embedding with policy document identifier and metadata
  5. Enable metadata filtering for precise query results
  6. Return success confirmation with embedding reference

Job: Update Policy Embeddings

User Story: As a policy administrator, I want to update embeddings when policy documents change, so that semantic search reflects current governance rules.

EARS Requirement:

• While the system is operational, when an UpdateEmbedding command is received with policy document identifier and new content, the memory context shall:
  1. Retrieve existing embedding by policy identifier
  2. Generate new 384-dimensional embedding vector from updated content
  3. Replace existing embedding with new vector
  4. Update metadata timestamp to reflect modification
  5. Maintain version history for embedding evolution tracking

Job: Search Policies by Semantic Meaning

User Story: As a policy consumer, I want to search for policies by semantic meaning (not just keywords), so that I can find relevant governance rules even when using different terminology.

EARS Requirement:

• While the system is operational, when a SearchEmbeddings query is received with natural language query text and similarity threshold, the memory context shall:
  1. Generate 384-dimensional embedding vector for query text
  2. Accept similarity_threshold in range 0.0–1.0 (default 0.75 if omitted)
  3. Execute cosine similarity search against stored policy embeddings
  4. Support pagination via offset/limit or cursor:
     • Default limit=50, max_limit=200
     • Enforce hard cap on returned results equal to limit
     • Optional max_results parameter must be <= limit
  5. Return policy documents exceeding similarity threshold
  6. Include similarity scores and document metadata in results
  7. Support metadata filtering for precise result refinement
  8. Rank results by semantic relevance
  9. Meet performance targets: median latency <=200ms; timeout after 2s (configurable) with a timeout error response

Job: Retrieve Policy by Embedding Reference

User Story: As a query system, I want to retrieve full policy documents by embedding reference, so that I can present complete governance rules to users.

EARS Requirement:

• While the system is operational, when a GetPolicyByEmbedding query is received with embedding reference identifier and origin (direct

  search), the memory context shall:

  1. Locate embedding by reference identifier
  2. Retrieve associated policy document content
  3. Return complete policy with metadata (title, content, source, timestamp)
  4. Include embedding similarity score only when origin == "search" (omit or null for direct lookups)
  5. Return null or 404 if embedding not found

Domain Entities Summary

Root Aggregates

• PolicyEmbedding: Represents a 384-dimensional vector embedding for semantic search with document identifier, vector array, and metadata

Value Objects

• EmbeddingVector: 384-dimensional float array for cosine similarity operations
• SimilarityResult: Query result with document reference and similarity score
• EmbeddingMetadata: Document attributes for filtering (title, source, tags, timestamp)

Policy Rules

• FixedDimensionality: Embeddings must be exactly 384 dimensions for compatibility
• CosineSimilaritySearch: Uses cosine similarity for semantic matching
• MetadataFiltering: Supports precise filtering by document attributes

Integration Points

• Ingest Context: Receives policy documents for embedding generation during ingestion pipeline
• Query Context: Provides semantic search capabilities for RAG query orchestration
• Semantic Core Context: Supplies validated DSL documents for embedding
• Governance Runtime Context: Supports evidence collection through policy retrieval
• PostgreSQL + pgvector: Vector storage and similarity search engine