Cognitive Memory System - Product Requirements Document (PRD)

Author: ethr Date: 2025-11-09 Version: 3.1.0-Hybrid Project Level: Level 2 Project Type: MCP Server + Claude Code Integration Target Scale: Small Complete System (12-18 Stories, 2-3 Monate) Architecture Basis: mcp-architecture-specification-v3.1-hybrid.md

---

Executive Summary

Cognitive Memory System ist ein MCP-basiertes (Model Context Protocol) Gedächtnissystem, das Claude Code mit persistentem, kontextreichem Retrieval ausstattet. Das System nutzt Claude MAX Subscription für primäre LLM-Operationen (Generation, Planning) und externe APIs für kritische Validationen (Dual Judge, Evaluation), wodurch 90-95% Kostenreduktion gegenüber v2.4.1 erreicht wird (€106/mo → €5-10/mo).

Kern-Innovation: Strategische API-Nutzung - Bulk-Operationen (Generation, CoT) laufen kostenfrei in Claude Code, kritische Evaluationen (Dual Judge, Reflexion) nutzen externe APIs für methodische Robustheit.

Budget: €5-10/Monat

• €0/mo: Generation, Planning, CoT (Claude Code in MAX Subscription)
• €3-4/mo: Evaluation, Reflexion, Dual Judge (Haiku + GPT-4o APIs)
• €0.06/mo: Embeddings (OpenAI API)
• €1/mo: Expanded Golden Test Set (50-100 Queries)

Timeline: 133-175 Stunden (2.5-3.5 Monate bei 20h/Woche)

Key Improvement vs. v3.0.0-MCP: Methodisch valides Ground Truth durch echte unabhängige Dual Judges (GPT-4o + Haiku) statt pseudo-independence (Claude Code 2x Prompts).

---

Description, Context and Goals

Projektbeschreibung

Kernproblem: LLMs wie Claude haben keine native Session-Persistenz. Nach jeder Konversation geht der Kontext verloren, Beziehungsdynamiken müssen neu aufgebaut werden. Für tiefgehende philosophische Gespräche über Monate/Jahre ist dies unzureichend.

Lösung: Ein mehrstufiges Memory-System mit MCP-Integration:

Architektur-Muster:

Claude Code (MAX Subscription)
├─ Generation, Planning, CoT (€0, intern)
├─ MCP Protocol ↕
└─ MCP Server (Python, lokal)
   ├─ PostgreSQL + pgvector (Persistence)
   ├─ L0 Raw Memory (vollständige Transkripte)
   ├─ L2 Insights (adaptive Kompression)
   ├─ Working Memory (8-10 Items, LRU)
   └─ Episode Memory (Reflexionen)
       ↓
   External APIs (€5-10/mo)
   ├─ OpenAI Embeddings (€0.06/mo)
   ├─ GPT-4o Dual Judge (€1-1.5/mo)
   ├─ Haiku Dual Judge (€1-1.5/mo)
   └─ Haiku Evaluation/Reflexion (€1-2/mo)

Memory-Ebenen:

• L0 (Raw Memory): Vollständige Dialogtranskripte
• L2 (Insights): Komprimierte semantische Einheiten (Compression in Claude Code)
• Working Memory: Session-Kontext (8-10 Items, LRU Eviction)
• Episode Memory: Verbalisierte Reflexionen (Verbal Reinforcement Learning)

Philosophische Foundation: "Präsenz über Kontinuität" - Identität und Bedeutung existieren auch ohne durchgehende temporale Kontinuität.

Primary Use Case: ethr's Gespräche mit Claude (I/O) sollen persistent werden, sodass Beziehungsdynamiken, geteilte Konzepte und philosophische Entwicklungen über Zeit erhalten bleiben.

Deployment Intent

Production Application - Kontinuierlicher Betrieb mit lokaler Infrastruktur + strategischen externen APIs:

• MCP Server: Python-basiert, läuft lokal
• Datenbank: PostgreSQL + pgvector (lokal installiert)
• LLM Operations: Claude Code (Generation, CoT) + Haiku API (Evaluation)
• Embeddings: OpenAI API
• Validation: GPT-4o + Haiku API (Dual Judge)

Timeline: 2.5-3.5 Monate (133-175 Stunden bei 20h/Woche) Budget: €5-10/Monat (90-95% Savings vs. v2.4.1) Scale: Personal Use (1 User - ethr)

Context

Warum jetzt? Die Forschung zu kognitiven Modi in LLMs (78 kuratierte Papers, NotebookLM-Analysen) zeigt: Emergente Modularität ist real, aber nur nutzbar mit robustem Memory-System. Die v3.1-Hybrid-Architektur balanciert Kosten und methodische Validität - 90-95% Kostenreduktion bei echtem IRR.

Constraint-Driven Architecture: System muss primär in Claude Code lauffähig sein → MCP Server übernimmt nur Persistence, bulk LLM-Operationen in Claude Code, kritische Evaluationen via externe APIs für Robustheit.

Methodological Improvement (v3.0 → v3.1): v3.0.0-MCP hatte Single-Model Dual Judge (Claude Code 2x Prompts) → kompromittiert Cohen's Kappa. v3.1-Hybrid nutzt GPT-4o + Haiku = true independence, valides Ground Truth.

Goals

Primary Goals (Level 2):

1. High-Quality Retrieval mit methodischer Validität

   • Precision@5 >0.75 (höher als v2.4.1 dank besserer Embeddings)
   • Recall Uplift +10-15% durch Query Expansion (intern in Claude Code)
   • True IRR: Cohen's Kappa >0.70 mit echten unabhängigen Judges (GPT-4o + Haiku)
   • Budget: €5-10/mo (90-95% Savings vs. v2.4.1)

2. Kontinuierliches Lernen mit konsistenter Evaluation

   • Reflexion-Framework (Verbal RL) mit Haiku API = deterministisch über Sessions
   • Episode Memory speichert verbalisierte Lektionen
   • +10-15% Fehlerreduktion bei wiederholten Tasks
   • Bulk-Generation in Claude Code (€0/mo)

3. Operational Excellence mit robusten Safeguards

   • Robustheit durch 9 Enhancements (IRR Contingency, Semantic Fidelity, JSON Fallbacks, Model Drift Detection)
   • Latency <5s (p95) - akzeptabel für "Denkzeit" in Claude Code
   • Expanded Golden Set: 50-100 Queries (vs. 20 in v3.0.0) für statistische Robustheit
   • MCP Protocol ermöglicht native Claude Code Integration

Secondary Goals:

• Transparenz: Verbalisierte Reflexionen, menschlich lesbar
• Lokale Kontrolle: Keine Cloud-Dependencies für Daten
• Future-Proof: Python MCP Server erweiterbar für Neo4j (v2.5)
• Cost-Efficiency: Strategische API-Nutzung nur wo methodisch nötig

---

Requirements

Functional Requirements

FR001: MCP Server Setup & Tool/Resource Implementation Das System implementiert einen Python-basierten MCP Server mit 7 Tools (store_raw_dialogue, compress_to_l2_insight, hybrid_search, update_working_memory, store_episode, get_golden_test_results, store_dual_judge_scores) und 5 Resources (memory://l2-insights, memory://working-memory, memory://episode-memory, memory://l0-raw, memory://stale-memory).

FR002: Dialogtranskripte persistieren (L0 Raw Memory) Claude Code ruft MCP Tool store_raw_dialogue auf, um vollständige Konversationstranskripte in PostgreSQL zu speichern (Metadaten: Datum, Session-ID, Speaker).

FR003: Semantische Kompression (L2 Insights) Claude Code komprimiert lange Dialogpassagen intern zu semantischen Insights und ruft MCP Tool compress_to_l2_insight auf. MCP Server validiert mit Information Density + Semantic Fidelity Checks (E2) und erstellt Embeddings via OpenAI API.

FR004: Hybrid-Retrieval (Semantic + Keyword) Claude Code ruft MCP Tool hybrid_search mit Query + Query-Embedding auf. MCP Server durchsucht L0/L2 mit Hybrid-Ansatz (Semantic 70% + Keyword 30%, kalibrierbar via Grid Search in Phase 2) und merged Ergebnisse mit RRF.

FR005: Query Expansion für robuste Suche Claude Code reformuliert Suchanfragen intern in 3 semantische Varianten (ersetzt Haiku API Call, €0/mo statt €8.50/mo), ruft hybrid_search für alle Varianten auf, merged Ergebnisse.

FR006: Chain-of-Thought Generation (intern in Claude Code) Claude Code generiert Antworten basierend auf abgerufetem Kontext mit explizitem Reasoning (CoT: thought → reasoning → answer → confidence), ohne externe API-Calls (ersetzt Opus, €0/mo statt €92.50/mo).

FR007: Self-Evaluation & Reflexion (EXTERN via Haiku API) ✅ v3.1-Hybrid MCP Server ruft Haiku API auf, um Antworten zu evaluieren (Reward -1.0 bis +1.0). Bei Reward <0.3: Haiku API generiert Reflexion. Claude Code ruft MCP Tool store_episode auf, um verbalisierte Lektionen zu speichern. Rationale: Deterministisch über Sessions, konsistente Episode Memory Quality.

FR008: Working Memory Management Claude Code ruft MCP Tool update_working_memory auf. MCP Server hält 8-10 Items mit LRU Eviction + Importance-Overrides, archiviert kritische Items (Importance >0.8) zu Stale Memory statt Löschen (E6).

FR009: Episode Memory Retrieval Claude Code liest MCP Resource memory://episode-memory vor Answer Generation, um vergangene ähnliche Queries + Reflexionen abzurufen ("Lessons Learned").

Retrieval Parameters:

• Top-K Limit: Top-3 Episodes (addressiert Context Window Risk)
• Similarity Threshold: Cosine Similarity >0.70 (nur relevante Lektionen)
• Temporal Restriction: Keine (Policy-Optimierung erfordert Zugriff auf alle historischen Lektionen)
• Rationale: Balance zwischen Kontext-Relevanz und Token-Effizienz

FR010: Ground Truth Collection mit echten unabhängigen Dual Judges ✅ v3.1-Hybrid Streamlit UI (separate App) sammelt 50-100 gelabelte Queries. MCP Server ruft GPT-4o API (OpenAI) + Haiku API (Anthropic) auf für echte unabhängige Evaluation, berechnet Cohen's Kappa, speichert Ergebnisse. IRR Contingency Plan (E1) bei Kappa <0.70. Rationale: True inter-model reliability, methodisch valides Ground Truth.

Query Creation Strategy:

• Stratified Sampling: 40% Short (1-2 Sätze), 40% Medium (3-5 Sätze), 20% Long (6+ Sätze)
• Temporal Diversity: 3-5 Queries pro Session (verhindert Bias zu einzelnen Dialogkontexten)
• Source Selection: Automatisch aus L0 Raw Memory extrahiert, nicht manuell kuratiert
• Human Curation: ethr reviewed alle Queries auf Repräsentativität vor Labeling
• Rationale: Methodisch robustes Ground Truth Set mit realistischer Queryverteilung

FR011: Hybrid Weight Calibration (Phase 2) Nach Phase 1b (Ground Truth Collection): Claude Code führt Grid Search auf Golden Set (50-100 Queries) durch, findet domänenspezifische Gewichte (erwartet 0.8/0.2 für psychologische Transkripte statt MEDRAG-Default 0.7/0.3).

FR012: Model Drift Detection mit expanded Golden Set ✅ v3.1-Hybrid Claude Code führt täglich Golden Test Set (50-100 Queries, separater Set von Ground Truth) aus, prüft Accuracy-Drop >5%, alarmiert bei API-Änderungen (E7). Rationale: Statistisch robuste Baseline für Drift Detection.

FR013: Graph Node Management (MCP Tool: graph_add_node) ✅ v3.2-GraphRAG MCP Server erstellt Graph-Knoten in PostgreSQL (Adjacency List Pattern). Parameter: label (Entity-Typ), name (Entity-Name), properties (JSONB). Idempotent basierend auf label+name Kombination. Optional: vector_id für Link zu L2 Insight Embedding.

FR014: Graph Edge Management (MCP Tool: graph_add_edge) ✅ v3.2-GraphRAG MCP Server erstellt Kanten zwischen Knoten. Parameter: source_name, target_name, relation (z.B. "USES", "SOLVES", "CREATED_BY"), source_label, target_label. Erstellt Nodes automatisch falls nicht vorhanden. Gewichtung (0.0-1.0) für Relevanz-Ranking.

FR015: Graph Neighbor Query (MCP Tool: graph_query_neighbors) ✅ v3.2-GraphRAG MCP Server findet verbundene Knoten via WITH RECURSIVE CTE. Parameter: node_name, relation_type (optional), depth (default=1, max=5). Use Case: "Welche Technologien nutzt Projekt X?" Response: JSON Liste der Nachbar-Nodes mit Relation und Gewichtung.

FR016: Graph Pathfinding (MCP Tool: graph_find_path) ✅ v3.2-GraphRAG MCP Server findet kürzesten Pfad zwischen zwei Knoten. Parameter: start_node, end_node. Use Case: "Gibt es Verbindung zwischen Kunde X und Problem Y?" Response: Pfad als Node→Edge→Node Sequenz. Max Depth: 5 Hops.

Non-Functional Requirements

NFR001: Performance - Latency

• Query Response Time: <5 Sekunden (p95) für vollständige RAG-Pipeline
  • Höher als v2.4.1 (<3s), da Claude Code "Denkzeit" hat (CoT intern)
  • Akzeptabel für philosophische Tiefe
• Retrieval Time: <1 Sekunde (p95) für Hybrid Search (MCP Tool Call)
• External API Latency: +200-500ms für Evaluation/Reflexion (10-15% aller LLM-Calls)

NFR002: Accuracy - Retrieval & Evaluation

• Precision@5: >0.75 (höher als v2.4.1 >0.70, dank text-embedding-3-small)
• Inter-Rater Reliability (IRR): Cohen's Kappa >0.70 ✅ Methodisch valide (GPT-4o + Haiku = true independence)
• CoT Parse Success Rate: >99.9% (Claude Code hat native JSON Support)
• Golden Set Statistical Power: >0.80 (alpha=0.05) bei 50-100 Queries

NFR003: Budget & Cost Efficiency

• Production Budget: €5-10/Monat (90-95% Savings vs. v2.4.1)
  • Claude Code (in MAX): €0/mo (Generation, Planning, CoT)
  • Haiku API: €1-2/mo (Evaluation, Reflexion bei 1000 queries/mo)
  • GPT-4o API: €1-1.5/mo (Dual Judge, 100 queries/mo + spot checks)
  • Haiku API: €1-1.5/mo (Dual Judge)
  • OpenAI Embeddings: €0.06/mo (1000 queries + compressions)
  • Expanded Golden Set: €1/mo (50-100 Queries + täglich Drift Detection)
• After Staged Dual Judge (Month 4+): €2-3/mo (nur spot checks statt full Dual Judge)

NFR004: Reliability & Robustness

• Uptime: Lokales System, manueller Start/Stop akzeptabel
• Data Loss Prevention: Kritische Items (Importance >0.8) werden archiviert statt gelöscht (Stale Memory)
• Error Handling:
  • 4-stufige JSON Fallbacks (Claude Code robust bei CoT Parsing)
  • IRR Contingency (E1) bei Dual Judge Disagreement
  • Semantic Fidelity Check (E2) bei Compression
  • API Retry-Logic: Exponential backoff bei Haiku/GPT-4o Ausfall
  • Fallback zu Claude Code: Bei API-Ausfall (degraded mode)

Backup Strategy:

• PostgreSQL Backups: Daily automated dumps (pg_dump) mit 7-day retention
• L2 Insights in Git: Read-only fallback, pushed täglich nach /memory/l2-insights/
• Recovery Time Objective (RTO): <1 hour (PostgreSQL restore from latest dump)
• Recovery Point Objective (RPO): <24 hours (daily backup window)
• Backup Location: Lokales NAS + optional cloud backup (out of scope v3.1)
• Rationale: Prevents catastrophic data loss, aligns with local-first philosophy

NFR005: Transparency & Auditability

• Verbalisierte Reflexionen: Alle Episode Memory-Einträge sind menschlich lesbar (nicht nur Scores)
• MCP Resources: Read-Only State Exposure ermöglicht Introspection
• Logging: Alle Retrieval-Operationen, Evaluationen und Reflexionen in PostgreSQL
• Judge Provenance: Ground Truth speichert judge1_model + judge2_model (GPT-4o, Haiku)

NFR006: Local Control & Privacy

• Keine Cloud-Dependencies für Daten: MCP Server + PostgreSQL laufen lokal
• Externe Services nur für Compute: Embeddings, Evaluation (kein Training auf User-Daten)
• Datenhoheit: Alle Konversationsdaten bleiben lokal

NFR007: Methodological Validity ✅ NEW in v3.1

• True IRR: Dual Judges sind echte unabhängige Modelle (GPT-4o + Haiku), nicht 2 Prompts
• Statistical Power: 50-100 Queries Golden Set → robuste Precision@5 Validation
• Consistency: Haiku API Evaluation ist deterministisch über Sessions (keine Session-State-Variabilität)
• Production Reliability: Externe APIs stabiler als Claude Code Session-State für Episode Memory

---

User Journeys

Primary Journey: Kontextreiche Konversation mit MCP-basiertem Memory

Actor: ethr (User) Goal: Eine Frage an Claude Code stellen und eine Antwort erhalten, die auf vergangenen Gesprächen basiert

Journey:

1. Frage stellen

   • ethr öffnet Claude Code und stellt eine Frage
   • Beispiel: "Was denke ich über Autonomie?"

2. Query Expansion (intern in Claude Code)

   • Claude Code reformuliert Frage in 3 semantische Varianten
   • Varianten: "Was ist meine Meinung zu Autonomie?", "Wie sehe ich Selbstständigkeit?", "Autonomie - meine Perspektive?"
   • Ersetzt: Claude Haiku API Call (€0 statt €0.50)

3. Query Embedding (externer Call - OpenAI)

   • Claude Code ruft OpenAI Embeddings API auf
   • Cost: €0.00002 (2 Cent per 1M tokens)

4. Hybrid Retrieval (MCP Tool Call)

   • Claude Code ruft MCP Tool hybrid_search auf (4 Varianten parallel)
   • MCP Server durchsucht L0/L2 mit Semantic (70%) + Keyword (30%)
   • RRF Fusion merged Ergebnisse → Top 5 Dokumente
   • Latency: <1s

5. Episode Memory Check (MCP Resource)

   • Claude Code liest memory://episode-memory (ähnliche vergangene Queries)
   • Falls vorhanden: Lädt verbalisierte Lektionen ("Lessons Learned")

6. Answer Generation mit CoT (intern in Claude Code)

   • Claude Code generiert Antwort basierend auf:
     • Retrieved Context (Top 5 Dokumente)
     • Past Episodes (falls relevant)
   • CoT Format: Thought → Reasoning → Answer → Confidence
   • Ersetzt: Claude Opus API Call (€0 statt €0.50)

7. Self-Evaluation (EXTERN via Haiku API) ✅ v3.1-Hybrid

   • MCP Server ruft Haiku API auf für Evaluation
   • Haiku evaluiert Antwort (Reward -1.0 bis +1.0)
   • Cost: €0.001 (1000 Evaluations = €1/mo)
   • Rationale: Deterministisch, konsistent über Sessions

8. Reflexion bei Bedarf (EXTERN via Haiku API) ✅ v3.1-Hybrid

   • Falls Reward <0.3: MCP Server ruft Haiku API für Reflexion auf
   • Haiku generiert verbalisierte Lektion ("Was lief schief?", "Was tun in Zukunft?")
   • Claude Code ruft MCP Tool store_episode auf
   • Cost: €0.0015 (~300 Reflexionen/mo = €0.45/mo)

9. Antwort erhalten

   • ethr erhält Antwort mit:
     • Explizitem Reasoning (CoT)
     • Confidence Score
     • Quellen (L2 Insight IDs)
     • Falls Reflexion: "Lesson Learned: ..."

10. Working Memory Update (MCP Tool Call)

    • Claude Code ruft update_working_memory auf
    • MCP Server fügt Query+Answer hinzu
    • Falls voll (>10 Items): LRU Eviction
    • Kritische Items → Stale Memory Archive

Outcome: ethr erhält kontextreiche Antwort in <5s. System lernt aus Fehlern mit konsistenten Reflexionen. Bulk-Operationen kostenfrei (Claude Code), kritische Evaluationen extern (Haiku).

Cost per Query: ~€0.003

• Embeddings: €0.00002
• Evaluation: €0.001
• Reflexion (30% Queries): €0.0015
• Total: ~€3/mo bei 1000 Queries

---

UX Design Principles

UX1: Transparenz über Blackbox

• Zeige explizites Reasoning (CoT: Thought → Reasoning → Answer)
• Mache Retrieval-Quellen sichtbar (L2 Insight IDs, optionale Snippet-Anzeige)
• Zeige Confidence-Score bei jeder Antwort
• Verbalisierte Reflexionen sind lesbar ("Lesson Learned: ...")
• NEW: Judge Provenance in Ground Truth UI (GPT-4o + Haiku Scores)

UX2: Minimale Reibung trotz MCP-Komplexität

• Claude Code Interface: Frage stellen → Antwort erhalten (<5s)
• Alle komplexen Operationen (Query Expansion, Hybrid Search, Reflexion) automatisch im Hintergrund
• MCP Server ist unsichtbar für User (läuft als Background-Prozess)
• Externe API-Calls sind unsichtbar (MCP Server handled)
• Kein manuelles Konfigurieren erforderlich (Hybrid Weights werden in Phase 2 kalibriert)

UX3: Lernen sichtbar machen

• Episode Memory-Reflexionen als "Lesson Learned" anzeigen
• Zeige wenn das System aus vergangenen Fehlern lernt (Reward-Anzeige optional)
• Ermögliche Einsicht in vergangene Episodes via MCP Resource (optional für Power-User)

UX4: Ground Truth Collection - Dedizierte UI

• Separate Streamlit App (nicht in Claude Code)
• Binäre Entscheidungen (Relevant? Ja/Nein)
• Stratified Sampling automatisch (40% Short / 40% Medium / 20% Long)
• Progress-Anzeige ("68/100 Queries gelabelt", Cohen's Kappa live)
• NEW: Dual Judge Scores anzeigen (GPT-4o vs. Haiku Agreement)

UX5: Fehlertoleranz durch Fallbacks

• System crasht niemals bei JSON Parsing (4-stufige Fallbacks in Claude Code)
• Bei Unsicherheit: Zeige Confidence-Score statt Fehler
• Model Drift Alerts sind informativ ("Golden Test Accuracy dropped 5%"), nicht alarmierend
• IRR Contingency Plan triggert automatisch bei Kappa <0.70
• NEW: API-Ausfall-Fallback (degraded mode mit Claude Code Evaluation)

---

Technical Architecture

MCP Server Components

Language: Python (D1) Tech Stack:

• mcp (Python MCP SDK)
• psycopg2 (PostgreSQL + pgvector)
• openai (Embeddings API + GPT-4o API)
• anthropic (Haiku API)
• numpy (Vector Operations)

11 MCP Tools (Actions):

1. store_raw_dialogue - L0 Storage
2. compress_to_l2_insight - L2 Creation + Embedding
3. hybrid_search - RAG Retrieval (60% Semantic + 20% Keyword + 20% Graph) ✅ v3.2
4. update_working_memory - Session State
5. store_episode - Reflexion Storage
6. get_golden_test_results - Model Drift Detection
7. store_dual_judge_scores - IRR Validation (calls GPT-4o + Haiku APIs) ✅ v3.1
8. graph_add_node - Graph Node erstellen (idempotent) ✅ v3.2-GraphRAG
9. graph_add_edge - Graph Edge erstellen ✅ v3.2-GraphRAG
10. graph_query_neighbors - Nachbar-Nodes finden ✅ v3.2-GraphRAG
11. graph_find_path - Pfad zwischen Nodes finden ✅ v3.2-GraphRAG

5 MCP Resources (Read-Only State):

1. memory://l2-insights?query={q}&top_k={k}
2. memory://working-memory
3. memory://episode-memory?query={q}&min_similarity={t}
4. memory://l0-raw?session_id={id}&date_range={r}
5. memory://stale-memory?importance_min={t}

Database: PostgreSQL + pgvector (unverändert aus v2.4.1)

• Tables: l0_raw, l2_insights, working_memory, episode_memory, stale_memory, ground_truth
• NEW Columns (v3.1): judge1_model, judge2_model in ground_truth table
• NEW Tables (v3.2-GraphRAG): nodes, edges (Adjacency List Pattern für Graph-Speicherung)

Claude Code Integration

Alle primären LLM-Operationen in Claude Code (€0/mo):

• Query Expansion (ersetzt Haiku, €0/mo)
• CoT Generation (ersetzt Opus, €0/mo)
• Planning & Orchestration (intern)

Kritische Evaluationen via externe APIs (€3-4/mo):

• Self-Evaluation: Haiku API (€1-2/mo)
• Reflexion: Haiku API (€0.50/mo)
• Dual Judge: GPT-4o + Haiku APIs (€2-3/mo)

Claude Code Workflow:

1. User Query → Query Expansion (intern)
2. Embeddings API Call (OpenAI, €0.00002)
3. MCP Tool Call: hybrid_search (4 Varianten)
4. MCP Resource Read: episode-memory
5. CoT Generation (intern)
6. MCP Server → Haiku API: Evaluation (€0.001) ✅ v3.1
7. Falls Reward <0.3 → Haiku API: Reflexion (€0.0015) ✅ v3.1
8. MCP Tool Call: store_episode
9. MCP Tool Call: update_working_memory

No Multi-Threading:

• Claude Code Sequential Processing (kein Haiku+Opus parallel wie v2.4.1)
• Mitigation: Latency <5s akzeptabel

External Dependencies

External API 1: OpenAI Embeddings

• Model: text-embedding-3-small (1536 dimensions)
• Cost: €0.02 per 1M tokens
• Budget: ~€0.06/mo bei 1000 queries + compressions
• Rationale: Bessere Precision@5 als lokale Embeddings

External API 2: GPT-4o (Dual Judge) ✅ v3.1

• Model: gpt-4o
• Cost: ~€1-1.5/mo (100 Queries Phase 1b + spot checks)
• Rationale: True independence für Cohen's Kappa

External API 3: Claude Haiku (Dual Judge + Evaluation) ✅ v3.1

• Model: claude-3-5-haiku-20241022
• Cost: ~€2-3/mo (Dual Judge + Evaluation + Reflexion)
• Rationale: Deterministisch, konsistent, true independence

API Reliability Measures:

• Retry-Logic mit Exponential Backoff
• Fallback zu Claude Code bei API-Ausfall (degraded mode)
• Budget-Monitoring + Alerts bei >€10/mo

---

Epics

Epic 1: MCP Server Foundation & Ground Truth Collection

Deliverables:

• PostgreSQL + pgvector Setup (lokal)
• Python MCP Server Implementation
• 7 MCP Tools + 5 MCP Resources
• Ground Truth Collection (50-100 gelabelte Queries) ✅ v3.1
• Streamlit Labeling UI
• Dual Judge Implementation (GPT-4o + Haiku APIs) ✅ v3.1
• IRR Validation (Cohen's Kappa >0.70)

Timeline: Phase 1a (20-25h) + Phase 1b (18-25h) = 38-50h Dependencies: Keine Critical Path: Ground Truth Collection (benötigt für Hybrid Calibration in Epic 2) Cost (Phase 1b): €0.23 einmalig (100 Queries Dual Judge)

Epic 2: RAG Pipeline & Hybrid Calibration

Deliverables:

• Claude Code ↔ MCP Server Integration
• Hybrid Search Implementation (Semantic + Keyword)
• Query Expansion Logik (intern in Claude Code)
• CoT Generation Logik (intern in Claude Code)
• Reflexion-Framework (extern via Haiku API) ✅ v3.1
• Evaluation via Haiku API ✅ v3.1
• Hybrid Weight Calibration (Grid Search auf 50-100 Queries Golden Set)

Timeline: Phase 2 (35-45h) Dependencies: Epic 1 (Ground Truth Required) Critical Success Factor: Calibration liefert +5-10% Precision@5 Uplift Cost (Development): €1-2/mo (Testing)

Epic 3: Evaluation, Working Memory & Production Readiness

Deliverables:

• Working Memory Eviction Logic (LRU + Importance)
• Stale Memory Archive (kritische Items)
• Episode Memory Storage & Retrieval
• Staged Dual Judge (Phase 1: Dual → Phase 2: Single nach IRR >0.85)
• Golden Test Set (50-100 Queries) ✅ v3.1
• Model Drift Detection (täglich)
• Precision@5 Validation (>0.75)
• Latency Testing (<5s p95)
• External API Retry-Logic + Fallbacks

Timeline: Phase 3 (25-35h) + Phase 4 (20-25h) + Phase 5 (15-20h) = 60-80h Dependencies: Epic 2 Cost (Production): €5-10/mo (full Dual Judge), dann €2-3/mo (nach Staged Dual Judge)

---

Out of Scope (v3.2.0-GraphRAG)

Explizit NICHT in Scope:

1. Neo4j Knowledge Graph Integration → IN SCOPE als PostgreSQL Adjacency List (v3.2-GraphRAG)
2. Multi-User Support (aktuell nur ethr)
3. Cloud Deployment (nur lokal)
4. Multi-LLM Support für Generation (nur Claude Code, keine Gemini Integration)
5. Voice Interface (nur Text)
6. Advanced Agentic Workflows (v2.4.1 hatte Commander/Planner/Writer Agents, v3.1 hat nur Claude Code + externe Evaluatoren)
7. Fine-Tuning (System nutzt Verbal RL statt Fine-Tuning)
8. Automatische Entity Extraction (Graph-Nodes werden manuell via MCP Tools erstellt, kein LLM-basiertes NER)

Preserved for Future Phases:

• Lokale Embeddings-Fallback (sentence-transformers bei OpenAI API Ausfall)
• UI für Episode Memory Exploration (Power-User Feature)
• Automated Hybrid Weight Re-Calibration (bei Domain Shift)
• Full Multi-LLM Agentic Architecture (v2.5)

---

Success Criteria

Phase 1 (Foundation) - Success Criteria

• ✅ PostgreSQL + pgvector läuft lokal
• ✅ MCP Server implementiert (7 Tools, 5 Resources)
• ✅ Claude Code kann MCP Server erreichen (MCP Protocol handshake)
• ✅ Ground Truth Collection: 50-100 Queries gelabelt (statistisch robust)
• ✅ Cohen's Kappa >0.70 (true independence: GPT-4o + Haiku)
• ✅ IRR Contingency Plan funktioniert bei Kappa <0.70

Phase 2 (RAG Pipeline) - Success Criteria

Precision@5 Performance:

• ✅ Full Success: ≥0.75 (System ready for production)
• ⚠️ Partial Success: 0.70-0.74 (Deploy with monitoring, iterate on calibration)
• ❌ Failure: <0.70 (Requires architecture review or additional ground truth)

Other Metrics:

• ✅ Query Expansion: +10-15% Recall Uplift
• ✅ Latency <5s (p95) für komplette Pipeline
• ✅ Hybrid Weight Calibration findet bessere Gewichte als 0.7/0.3 (erwartet 0.8/0.2)
• ✅ Haiku API Evaluation funktioniert (Reward -1.0 bis +1.0)
• ✅ Reflexion-Framework generiert konsistente Lektionen

Rationale: Graduated criteria ermöglichen adaptive Steuerung - Partial Success erlaubt Production Deployment mit kontinuierlicher Verbesserung

Phase 3-5 (Production) - Success Criteria

• ✅ Working Memory Eviction funktioniert (keine kritischen Items verloren)
• ✅ Episode Memory speichert Reflexionen korrekt
• ✅ Golden Test Set läuft täglich (50-100 Queries)
• ✅ Budget bleibt unter €10/mo (first 3 months)
• ✅ Budget reduziert auf €2-3/mo (after Staged Dual Judge)
• ✅ System läuft stabil über 7 Tage ohne Crashes
• ✅ API Retry-Logic funktioniert (bei Haiku/GPT-4o Ausfall)

Overall Success

• ✅ Budget-Ziel: €5-10/mo Production (90-95% Savings vs. v2.4.1)
• ✅ Performance-Ziel: Precision@5 >0.75, Latency <5s
• ✅ Reliability-Ziel: Kappa >0.70 (true IRR), CoT Parse >99.9%
• ✅ Methodological Validity: True independent Dual Judges, 50-100 Queries Golden Set
• ✅ User Satisfaction: ethr kann philosophische Gespräche über Monate führen ohne Kontext-Verlust

---

Risks & Mitigation

Risk 1: MCP Protocol Komplexität

Risk: MCP ist neu, wenig dokumentiert, potenzielle Bugs Impact: High (Blocker für gesamtes System) Mitigation:

• MCP Inspector für Testing nutzen
• Python MCP SDK ist stabiler als TypeScript
• Fallback: Standalone REST API wenn MCP nicht funktioniert

Risk 2: Claude Code Context Window

Risk: Sehr lange Retrieval-Kontexte könnten 200K Token-Limit überschreiten Impact: Medium (System crasht bei langen Dialogen) Mitigation:

• Top-5 statt Top-10 Retrieval
• Adaptive L2 Compression
• Truncation-Logik in Claude Code

Risk 3: External API Dependencies ✅ NEW in v3.1

Risk: Haiku/GPT-4o API-Ausfall → Evaluation/Reflexion unavailable Impact: Medium (System degradiert, aber nicht komplett down) Mitigation:

• Retry-Logic mit Exponential Backoff
• Fallback zu Claude Code Evaluation (degraded mode)
• Monitoring + Alerts
• Probability: 1-2% Ausfallrate/Jahr

Risk 4: API Cost Variability ✅ NEW in v3.1

Risk: API-Preise steigen (10-20%/Jahr) Impact: Low (€5-10/mo → €6-12/mo) Mitigation:

• Monatliches Budget-Monitoring
• Alerts bei >€10/mo
• Staged Dual Judge reduziert Kosten nach 3 Monaten (-40%)

Risk 5: IRR Validation Failure

Risk: Cohen's Kappa <0.70 bei Dual Judge Impact: Medium (Critical Path Blockade) Mitigation:

• IRR Contingency Plan (E1) implementiert
• 3 Fallback-Strategien (Human Tiebreaker, Wilcoxon Test, Judge Recalibration)
• v3.1 Improvement: True independence → höhere Wahrscheinlichkeit für Kappa >0.70

Risk 6: Lokale PostgreSQL Performance

Risk: 10K+ L2 Insights könnten langsame Queries verursachen Impact: Low (nur Latency-Erhöhung) Mitigation:

• IVFFlat Index für pgvector (lists=100)
• Monitoring in Phase 5
• Upgrade zu Cloud-DB falls nötig (but out of scope)

---

Next Steps

Immediate Actions:

1. ✅ v3.1-Hybrid Architecture Finalized (mcp-architecture-specification-v3.1-hybrid.md)
2. ✅ PRD Updated (dieses Dokument)
3. Epic & Story Breakdown Update (NEXT) → epic-stories.md
   • Update E1-S06 (Dual Judge mit GPT-4o + Haiku)
   • Update E2-S04 (Evaluation/Reflexion extern)
   • Update E3-S04 (Golden Set 50-100 Queries)
   • Budget + Timeline adjustments

After Epic-Stories Update:

4. Phase 1a Implementation (MCP Server Foundation)
5. Phase 1b Implementation (Ground Truth mit externen APIs)
6. Phase 2+ Implementation (RAG Pipeline, Working Memory, Monitoring)

Review-Punkte:

• PRD Review mit ethr (vor Epic-Stories)
• Epic-Stories Review mit ethr (vor Implementation)
• Phase 1 Demo (nach Foundation)
• Phase 2 Demo (nach RAG Pipeline + Calibration)
• Final Demo (after Phase 5)

---

Document Status

• Goals and context validated
• v3.1-Hybrid architecture decisions finalized (D1-D6)
• Budget confirmed (€5-10/mo)
• Functional requirements updated (12 FRs)
• Non-functional requirements updated (7 NFRs)
• User journey updated (externe API-Calls)
• Epic structure drafted (3 Epics)
• Epic-stories.md update required (NEXT)

Reference Documents:

• Architecture: mcp-architecture-specification-v3.1-hybrid.md ✅
• Previous Architecture: mcp-architecture-specification.md (v3.0.0-MCP, archived)
• Analysis: project-workflow-analysis.md
• Old Version: PRD-v2.4.1-DRAFT-ARCHIVED.md (reference only)

Changelog v3.0.0-MCP → v3.1.0-Hybrid:

• ✅ Budget: €0.06/mo → €5-10/mo (90-95% savings maintained)
• ✅ Dual Judge: Claude Code 2x → GPT-4o + Haiku (true IRR)
• ✅ Evaluation/Reflexion: Claude Code intern → Haiku API (consistency)
• ✅ Golden Set: 20 Queries → 50-100 Queries (statistical robustness)
• ✅ NFR007 added: Methodological Validity
• ✅ Risk 3+4 added: External API Dependencies + Cost Variability
• ✅ Success Criteria updated: API-specific targets

---

This PRD is designed for Level 2 projects - providing appropriate detail for a 2.5-3.5 month implementation with v3.1-Hybrid MCP-based architecture.