---
title: Aria Brain Think-Layer — Synthesis + Gap Analysis
type: reference
tags: [aria, brain, search, think, gap-analysis, kar-622]
date: 2026-05-25
status: aktiv
source: /root/aria/scripts/aria-brain-think.py
confidence: high
---

# Aria Brain Think-Layer — Synthesis + Gap Analysis

> KAR-622. Implementiert 2026-05-25. Ergänzt den bestehenden `search`-Layer um einen `think`-Layer.

## Think vs Search: der konzeptuelle Split

Das Brain hat jetzt zwei Query-Modi:

| | `search` (aria-brain-search.py) | `think` (aria-brain-think.py) |
|---|---|---|
| **Output** | Gerankte Treffer-Liste | Synthetisierte Antwort + Quellen + Gap-Report |
| **Ziel** | "Wo steht was zu X?" | "Was weiß das Brain über X? Was fehlt?" |
| **Modell** | BM25 + Recency + Path-Boost | Search → Extraktion/LLM-Synthese → Gap-Analyse |
| **Kosten** | Null (rein lokal) | Lokal extraktiv oder cheap LLM (~$0.001/Anfrage) |
| **Offline** | Immer | `--no-llm` Flag |

Inspiriert von gbrain's `gbrain think` vs `gbrain search` Design (analysiert in `qmd-vs-aria-brain-benchmark-2026-05-24`).

## Gap-Analyse-Heuristiken

Der Think-Layer ergänzt die Antwort mit 4 Lücken-Kategorien:

### STALE
Treffer deren `date`-Frontmatter (oder file mtime) älter als `--stale-days` (Default: 90 Tage) ist.
- Priorisiert Frontmatter-Datum (`date:` Feld)
- Fallback auf mtime wenn kein Frontmatter-Datum
- Gibt `age_days` und den Grund (`frontmatter date YYYY-MM-DD` vs `file mtime Nd ago`) aus

### UNCITED
Query-Token die in der Antwort nicht vorkommen.
- Im LLM-Modus: Differenz Query-Token vs Answer-Token
- Im extraktiven Modus: Token die in keinem ausgewählten Satz auftauchen
- Signal: "Diese Aspekte des Query wurden in der Synthese nicht adressiert"

### CONTRADICTION
Heuristisches V1-Signal wenn zwei Treffer-Dokumente:
- Mehr als 3 gemeinsame Key-Token teilen (länger als 3 Zeichen)
- Aber eines einen Negations-Kontext hat (kein/nicht/never/no/deprecated/veraltet) und das andere nicht

Kein Semantic-Reasoning — nur statistisches Warnsignal. Muss manuell verifiziert werden.

### MISSING
Query-Aspekte die in keinem Treffer-Dokument vorkommen.
- Differenz zu UNCITED: MISSING = Term nicht im Brain-Content, UNCITED = Term im Brain aber nicht zitiert
- Liefert konkrete Hinweise was ins Brain dokumentiert werden sollte

## LLM-Konfiguration

Cheapest-First-Fallback-Kette:
1. Gemini 2.0 Flash (`GEMINI_API_KEY` aus `/root/.aria-secrets/gemini.env`)
2. DeepSeek Chat (`DEEPSEEK_API_KEY` aus `/root/.aria-secrets/deepseek.env`)
3. GPT-4o-Mini (`OPENAI_API_KEY` aus `/root/.aria-secrets/openai.env`)

Wenn alle Provider scheitern (Rate Limit, Netz) → graceful fallback auf extraktive Synthese.

Max 512 Output-Tokens pro LLM-Call. Prompt enthält maximal 400 Zeichen Preview pro Treffer.

## Usage

```bash
# Standard (mit LLM wenn Key vorhanden)
aria-brain-think "BMW Design System Farben"

# Offline / deterministisch
aria-brain-think "Kadi-v2 Datenbankschema" --no-llm

# Mehr Treffer, strengere Staleness-Grenze
aria-brain-think "Aria Architektur Status" --top 10 --stale-days 30

# JSON-Output (für Skript-Integration)
aria-brain-think "Linear KAR Backlog" --json | jq .gaps
```

## MCP-Tool

Seit KAR-622 ist `brain_think` als MCP-Tool in `/root/aria/mcps/aria-brain/server.py` exponiert.
Kein Subprocess-Overhead — wird direkt in-process aufgerufen.

```python
# MCP-Tool-Signatur
brain_think(query: str, top_n: int = 7, no_llm: bool = False, stale_days: int = 90) -> str
```

## Architektur-Entscheidungen

- **Kein BM25-Reimport**: `aria-brain-search.py` wird via `importlib.util` als Modul importiert. Kein Code-Duplizierung, keine Subprocess-Latenz.
- **Deterministische Extraktion immer verfügbar**: `--no-llm` funktioniert offline ohne API-Key.
- **Token-Budget klein halten**: nur 400 Zeichen Preview pro Treffer im Prompt. Reicht für Synthese, hält Kosten minimal.
- **Graceful Degradation**: LLM-Fehler (Rate-Limit, Timeout, Netz) → automatisch extraktiv, kein Crash.

## Bekannte Limitierungen (V1)

- CONTRADICTION-Heuristik ist sehr simpel — keine semantische Analyse
- UNCITED basiert auf Token-Overlap, nicht auf semantischem Matching
- Extractive-Synthese kann abgehackt wirken bei kurzen Previews
- LLM-Antworten sind manchmal zu ehrlich ("ich weiß das nicht") wenn die Brain-Docs dünn sind

## Weiterentwicklung (follow-up KARs möglich)

- Semantic CONTRADICTION via embedding distance zwischen Treffer-Paaren
- STALE-Kategorisierung nach Content-Type (reference Notes veralten langsamer als daily/status Notes)
- Interaktiver Think-Mode: Gap-Lücken direkt in Brain schreiben anbieten