AI-Memory-System — Persistentes Gedächtnis für die KIera-KI

Diese Seite beschreibt die Architektur, wie sie im BE-Branch `ai-memory-system` umgesetzt ist (gemergt in `master` mit Welle-140-relevanten Commits). Konkrete Implementierungs-Details und Edge-Cases liegen in den Tasks-Briefings unter `api.speamcore.com/tasks/2026-04-30_ai-memory-system/` (TASK, ARCHITECTURE, DECISIONS, PROGRESS).

Die KIera-KI hatte bisher kein Gedächtnis — jeder Chat-Aufruf startete im Kontext-Nirgendwo, jedes „Mit wem haben wir letzte Woche das Mahn-Konzept abgestimmt?" lief gegen leere Datenbank. Das Memory-System ändert das: Pro Mandant entsteht ein persistentes Wissen, das aus Chat-Verläufen, Geschäftsereignissen und expliziten Markierungen wächst; pro User kommt eine persönliche Memory-Schicht dazu.

Das System ist in mehreren Schichten gebaut — von der Observation (kleinste Wissens-Einheit) bis zur Auto-Modell-Wahl + Advisor-Strategy zur Kostenoptimierung.

Architektur

Drei Trigger erzeugen neue Observations:

1. Sequelize-Hooks auf Schreib-Operationen (Kunde angelegt, Auftrag abgeschlossen, Beleg storniert).
2. Chat-Turn-Ende — die KI extrahiert aus dem letzten Verlauf, was bleiben soll.
3. Manuelle Markierung — User klickt im Chat „merken" auf eine Aussage.

Alle drei laufen über BullMQ asynchron, damit der User keine Latenz spürt.

Datenmodelle

AiObservation — die zentrale Gedächtnis-Einheit

Feld	Wirkung
type	fact / decision / event / concept / …
title, narrative	menschenlesbarer Kurz-/Lang-Text
facts, concepts	Arrays für strukturiertes Filter
userId (nullable)	NULL = mandantenweit; gesetzt = persönliche Memory
contentHash	SHA256 — Dedup beim Anlegen
discoveryTokens	Tokens, mit denen die Observation gefunden wird
relevanceCount	wie oft retrieved (Sortier-Kriterium)
scope	private / team / public / sensitive
triggerSource	chat / hook / manual / consolidation

AiObservationFeedback

Tracking: retrieved (zur Antwort gezogen), cited (in Antwort erwähnt), confirmed (User bestätigt), rejected (User verwirft). Steuert künftige Retrieval-Relevanz.

AiSession und AiSummary

• AiSession: Wrapper um einen Chat-Verlauf. Felder: userId, userPrompt, status (active / completed / failed), metadata.
• AiSummary: strukturierte Session-Zusammenfassung mit Feldern request, investigated, learned, completed, nextSteps, notes, generatedByModel.

AiEvent — Telemetry-Eventlog

Append-only, strukturiert. Pro Event ein eventName + metadata-JSON. Quelle für das Telemetry-Dashboard (siehe unten).

ChatMessage / Chat (erweitert)

• ChatMessage.durationMs — End-to-End-Antwortzeit
• ChatMessage.memoryTrace — Trace der gezogenen Observations, Tool-Calls, Extraction-Status
• Chat.kind (ai | user) — explizit, ersetzt die alte Heuristik anhand der Teilnehmer-Anzahl

Auto-Modell-Wahl

autoModelSelection.service.ts klassifiziert jeden Prompt vor dem LLM-Call:

Klasse	Erkennung	Modell
Trivial	Greetings, kurze Eingaben (< 10 Wörter)	Sonnet (Default)
Complex	Keywords wie architecture, refactor, tradeoff, risk, strategy	Opus (smart)
Default	alle anderen	Sonnet (kosten-optimiert)

Reason-Tracking landet in chat.model_auto_routed-Events (selectedModel, tier, reason, confidence).

Advisor-Strategy (consult_advisor-Tool)

Two-Tier-Agentic: Executor (Sonnet/Haiku) führt 80 % der Turns aus. Erkennt der Executor eine wirklich harte Entscheidung (Architektur, Risiko, mehrdeutige Anforderung), ruft er das consult_advisor-Tool auf und bekommt eine Antwort vom Opus-Modell zurück. Danach läuft der Executor weiter.

Effekt: Im Durchschnitt Opus-Qualität bei Sonnet-Preisen. Telemetry-Event: chat.advisor_auto_triggered mit trigger, executorModel, durationMs.

Server-Side Compaction

Anthropic-Beta compact-2026-01-12 — die API komprimiert lange Verläufe server-seitig und gibt dem nächsten Turn nur eine zusammengefasste Variante mit.

Integration:

• ANTHROPIC_BETAS=compact-2026-01-12 ist Env-konfiguriert
• COMPACTION_SUPPORTED_MODELS ist ein Set (Opus 4.7/4.6, Sonnet 4.6, …) — Compaction wird nur bei diesen Modellen aktiviert
• buildRequest() patcht context_management.edits[] nur für supported Modelle
• detectAndLogCompaction() durchsucht die Response nach compaction-Blocks und protokolliert chat.compaction_fired mit summaryChars + iterationInputTokens
• sanitizeAssistantContent() whitelisted Block-Types (text, tool_use, thinking, compaction, …) bevor der Echo zurück an Anthropic geht

Telemetry-Dashboard

CASL-Gate: view FE_DevTools. Endpoints unter /api/ai/telemetry/*:

Route	Zweck	Query-Params
/overview	Aggregierte KPIs (turns, cost, tokens, errors, cache, ptl)	period=1h|24h|7d|30d
/events	Paginierte ai_events mit Filter	period, eventName, chatId, userId, page, size
/timeseries	Zeitreihe in hour/day-Buckets	metric, period, granularity
/top-tools	Top-N Tools (Calls, Avg-Duration, Success-Rate)	period, limit
/top-users	Top-N User nach Kosten	period, limit

Event-Taxonomie (alle Events sind typisiert):

Event	Wofür?
chat.turn_completed	Standard-Eintrag pro Antwort — model, Tokens, Cache, Kosten, Dauer, RAG-Hits
chat.tool_used	toolName, Dauer, Success
chat.error, chat.ptl_recovery	Fehler + Auto-Recovery
chat.approval_decision	User-Entscheidung bei vorschau-pflichtigen Aktionen
memory.extraction, memory.cache_break	Memory-Pipeline
chat.compaction_fired	Server-Side Compaction griff
chat.model_auto_routed, chat.advisor_auto_triggered	Auto-Routing + Advisor

Retention

Cron-Job telemetryCleanup.service.cleanupAiEvents() — täglich um 03:30 Europe/Berlin, löscht Events älter als AI_EVENTS_RETENTION_DAYS (Default 90).

Embedding-Stack

Der Übergang von ELSER (Sparse-Vektoren, Elastic-Lizenz) auf BGE-M3 (Dense-Vektoren, Apache 2.0) ist in ADR-018 im Tasks-Folder dokumentiert:

• HTTP-Client embedding.service.ts ruft TEI_EMBEDDING_URL (Text-Embeddings-Inference-Sidecar als Kubernetes-Service)
• Modell BAAI/bge-m3, 1024-dim, multilingual
• Elasticsearch-Index nutzt dense_vector (cosine-similarity)
• Hybrid-Suche kombiniert BM25 (lexical) + kNN (semantic) per retriever.rrf

Memory-Scopes

Scope	Wer sieht es?
private	nur der erzeugende User
team	User-Gruppe (Department/Rolle)
public	alle Mandanten-User
sensitive	nur User mit view:SensitiveAiMemory-Permission (z. B. HR/GF), wird in Standard-Antworten nicht referenziert

userId = NULL plus scope = public → deployment-weite Observation, die für jeden User mandantenweit zugänglich ist.

CASL

Neue Subjects:

Subject	Wofür?
AiEvent	Lesen der Telemetry-Events
AiObservation	Lesen / Anlegen / Bearbeiten von Memory-Einheiten
AiObservationFeedback	Feedback-Loop
AiSession, AiSummary	Session-Verlauf
FE_DevTools	Frontend-Gate für das Telemetry-Dashboard

Environment-Variablen (Kurzreferenz)

AI_MEMORY_PROVIDER=dense_vector
TEI_EMBEDDING_URL=http://tei-embedding.speamcore.svc.cluster.local
TEI_EMBEDDING_MODEL=BAAI/bge-m3
TEI_EMBEDDING_DIMENSIONS=1024

ANTHROPIC_BETAS=compact-2026-01-12
ANTHROPIC_AUTO_SONNET_MODEL=claude-sonnet-4-6
ANTHROPIC_AUTO_OPUS_MODEL=claude-opus-4-7
ANTHROPIC_ADVISOR_MODEL=claude-opus-4-7

AI_EVENTS_RETENTION_DAYS=90

Was die Engine NICHT macht

• Kein Lernen aus Fehlern in Real-Time — Feedback fließt erst im nächsten Retrieval ein (relevanceCount).
• Keine automatische Korrektur falscher Observations — User muss explizit rejected-Feedback geben oder via manual neue, richtige Observation anlegen.
• Kein Cross-Tenant-Lernen — strikte Mandanten-Trennung, jeder Tenant hat eigene Indices.
• Kein Vergessen ohne Retention — eine Observation lebt, bis sie aktiv gelöscht oder durch consolidation zusammengelegt wird.

Verknüpfungen

• KI-Chat-Architektur — der Tool-Use-Loop, in dem das Memory-System eingebettet ist.
• Berechtigungen / CASL — view FE_DevTools und view:SensitiveAiMemory.
• Tasks-Briefings im BE-Repo: tasks/2026-04-30_ai-memory-system/{TASK,ARCHITECTURE,DECISIONS,BRIEFING_DO_TEI,PROGRESS}.md.

Versionshinweise

• 2026-05-21 (Welle 140): Initiale Veröffentlichung. Quelle: BE-Branch ai-memory-system (Merge in master mit Commits cca2d560, 0036e744, 0e81de1d, 4c2d82f9, 90f924db, 34fdd2f6, 554d98ee, 199662f9, e619dbda, ddcd8509). Neue Models AiObservation, AiObservationFeedback, AiSession, AiSummary, AiEvent; Services autoModelSelection, advisor, telemetry, telemetryQuery, telemetryCleanup, embedding (BGE-M3 statt ELSER); 5 Telemetry-Endpoints unter /api/ai/telemetry/*; Cron-Cleanup täglich 03:30; ChatMessage um durationMs + memoryTrace erweitert; Chat.kind-Feld explizit.