Implementation Plan: Temporal Memory and Pattern Oracle

Learn from history and feed recommendations into synthesis and governance by implementing the Temporal Database subsystem (VectorStore + PatternOracle + MetricIndexer). This plan operationalizes institutional memory as deterministic, queryable artifacts.

Provenance & Traceability

Architectural Decisions (ADRs)

Product Requirements (PRDs)

Software Design Specifications (SDS)

Provenance Chain

graph TD
  ADR30[ADR-030: VibesPro™ Foundation] --> PRD20[PRD-020: VibesPro™ Foundation Platform]
  PRD20 --> SDS15[SDS-015: Temporal Database Service]
  PRD20 --> SDS45[SDS-045: Foundation Integration]
  ADR29[ADR-029: Observability] --> SDS15

Architecture and Design

Design Principles Applied

• Isomorphism: Pattern embeddings and recommendations carry traceability to specs and identity tokens (SDS-015 policies).
• Invariants: Local-first privacy (SDS-015 Policy LocalFirstPrivacy).
• Idempotency: Recording outcomes and embeddings dedupes by identity token / canonical hash.

Dependency Justification

Updated 2025-12-30: Added specific dependencies from gap analysis section 1.3 (Temporal Database / Semantic Memory).

Installation Commands

1
2
3
4
5
6
7
8
9
10
11
12
# PostgreSQL extensions (in Docker or migration)
CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS timescaledb;

# Python dependencies
pip install pgvector psycopg[binary] llama-cpp-python

# llama.cpp CLI (via mise)
mise use llama-cpp@latest

# Download embedding model
wget -P models/ https://huggingface.co/google/EmbeddingGemma-7B-GGUF/resolve/main/EmbeddingGemma-300M-Q4_K_M.gguf

Semantic Memory Port Architecture

1
2
3
4
5
6
// Semantic Memory Port (wraps pgvector + llama.cpp)
interface SemanticMemoryPort {
  storeObservation(content: string, metadata: Metadata): Promise<VectorId>;
  findSimilar(query: string, limit: number): Promise<ScoredObservation[]>;
  generateEmbedding(text: string): Promise<Float32Array>;
}

Expected Filetree

1
2
3
4
/
├── docs/specs/semantic-core/sds/015-temporal-database-service.md
├── docs/specs/shared/prd/020-vibespro-foundation-platform.md
└── docs/specs/shared/sds/045-vibespro-foundation-integration.md

Proposed Cycles

Task Breakdown

Wave 1 (Parallel)

• C1A: Lock Temporal DB API semantics (VectorStore, PatternOracle, MetricIndexer)
  • Implements: SDS-015 flows (StoreEmbedding, RetrieveSimilar, QueryPatterns, RecommendPatterns, IndexTelemetry)
  • Satisfies: PRD-020 US-001/US-002
  • Files: docs/specs/semantic-core/sds/015-temporal-database-service.md
• C1B: Define the governance + performance signals that feed pattern weighting
  • Implements: MetricIndexer ingestion contract and required fields
  • Satisfies: “similarity + performance + governance” ranking claim in SDS-015
  • Files: docs/specs/shared/adr/029-observability-stack-architecture.md, docs/specs/shared/sds/030-semantic-observability.md

Wave 2 (Depends on Wave 1)

• C2A: Wire pattern recommendations into generation planning (VibesPro™ integration)
  • Implements: SDS-045 “RecommendPatterns” flow into generation planning
  • Satisfies: PRD-020 foundation goals
  • Files: docs/specs/shared/sds/045-vibespro-foundation-integration.md

Validation & Verification

Spec Validation

• Ensure SDS-015 policies reference identity tokens for uniqueness (SemanticMemoryIntegrity)
• Ensure privacy constraints are explicit (LocalFirstPrivacy)

Implementation Validation

• Pattern queries return ranked results with success rates and risk levels (SDS-015)
• Telemetry ingestion updates pattern statistics deterministically (RefreshStats)

Open Questions

1. Where are the “success rate” and “risk level” metrics sourced from (OpenObserve vs governance evidence vs both)? Both (spans + evidence)
2. What is the canonical embedding model and dimensionality (and where is it configured)? text-embedding-3-small (1536 dims)
3. What is the retention policy for embeddings and telemetry-derived aggregates? Embeddings indefinite, aggregates 1yr

Risks & Mitigation

Rollback Strategy

1. If MetricIndexer is unstable, run PatternOracle in “similarity-only” mode until telemetry ingestion is reliable.

Related Documents

Linked Specifications