# Agent-Memory — pv-agent

Rollender Übergabe-Log für agent-Threads. Workflow: `.agents/SKILL.md`
(agent-memory-Skill). Ergänzen, nicht überschreiben.

## Current focus

M1 (Index + Retrieval) und M2 (Ollama-Generierung + Grounding + API) sind
implementiert. Ausstehend: Host-Validierung mit Ollama (Dense-Index,
Antwortmodus-Eval) und Modell-Bake-off (M3). Odoo-Integration (M4) ist
separat zu planen.

## Completed (2026-09-14)

- **Planung** (`planung.md`): Architektur, Grounding-Regeln, Modellfeld
  (Bake-off: qwen3.8:27b primär, qwen3:32b, gemma3:27b, mistral-small3.2:24b,
  qwen3:14b als Latenz-Untergrenze), Meilensteine M1–M4.
- **Skill** `.agents/skills/pv-rag-agent/SKILL.md`: verbindliche Regeln für
  die Implementierung (Grounding, Architektur-Entscheidungen, Gates,
  Modellwechsel-Protokoll).
- **Commits**: `25eb285` (Wissensbasis-Import 601 Layer-2-Einträge +
  .gitignore), `bf8191b` (Planung + Skills). Noch nicht gepusht — Remote
  `http://localhost:3003/fegger/pv-agent.git` ist aus der Zed-Sandbox nicht
  erreichbar; User muss vom Host pushen.
- **Implementierung M1+M2** (`agent/`-Paket): kb.py (Parsing + kb.json-Gate),
  ingest.py (3005 Chunks aus 601 Einträgen, FTS5 + Vektoren-Cache),
  retrieve.py (Hybrid BM25+Dense/RRF, Stand-Boost, cross_ref-Erweiterung),
  generate.py (Systemprompt, Post-Validierung, 1× Regenerierung, dann
  Verweigerung), ollama_client.py (embed/chat, think-Flag-Fallback),
  api.py (/ask /health /reindex), cli.py, eval/ (Goldset 31 Fragen,
  evaluate.py), web/index.html, 41 offline Tests (grün).
- **Baseline BM25-only**: Hit-Rate 0,871 · Recall@8 0,855 · MRR 0,476
  (31 Fragen). 4 Fehltreffer: Komposita/Stamm-Schwächen (aliquotiert↔
  Aliquotierung, Mindestlohngesetz) — Dense-Suche soll diese beheben.

## Open issues / blockers

- **Ollama aus Zed-Sandbox nicht erreichbar** (100.183.83.12:11435 und
  localhost:3003 beide geblockt): Dense-Index, Antwortmodus-Eval und
  Bake-off müssen auf dem Host laufen. Kommandos: `agent/README.md`
  Abschnitt „Deployment auf dem Host".
- **Modelle noch nicht gepullt**: auf dem Host `ollama pull qwen3.8:27b`,
  `ollama pull bge-m3` (plus Bake-off-Kandidaten).
- **Reranker** (bge-reranker-v2-m3): API-Unterstützung der installierten
  Ollama-Version prüfen — Design funktioniert ohne.
- **qwen3.8-Think-Parameter**: `think: false` wird im Request gesendet
  (Auto-Fallback ohne Flag bei 400/404); exaktes Verhalten am Host testen.
- **M4 Odoo**: native LLM-Module des konkreten Odoo-19-Stands verifizieren
  (keine API-Annahmen); Option A (dünnes Custom-Modul + Service-API) ist
  Default.

## Decisions & conventions

- **D1 (Planung):** Schlanke Eigen-Pipeline statt LangChain/LlamaIndex —
  Grounding-Kontrolle schlägt Framework-Komfort bei 601 Dokumenten.
- **D2:** Retrieval-Korpus ist **nur Layer 2**; Layer 1 bleibt aus Prompts
  (Lizenz); Antworten zitieren `[kb-id]` + `(Stand YYYY-MM)`.
- **D3:** Umlaut-Folding für FTS (NFKD, ß→ss) — gilt konsistent für Index
  und Query; ASCII-Slug-Konvention der Wissensbasis bleibt davon unberührt.
- **D4:** Post-Validierung strikt: zitierte IDs ⊆ Retrieved-Set (Block-Kopf-
  IDs); Fließtext-Verweis-IDs sind KEINE Belege (Systemprompt-Regel 2) —
  Verstoß → 1× Regenerierung → Verweigerung (UNCERTAIN_MESSAGE).
- **D5:** Vektoren-Tabelle ist Cache (Content-Hash × Modell), Rebuild
  löscht sie nicht; `--no-embed` setzt `embed_off` im Config-Copy.
- **D6:** Leeres Retrieval → deterministische Verweigerung ohne LLM-Call.
- **Bake-off-Protokoll** (Skill): Modellwechsel nur über dokumentierten
  Goldset-Vergleich; Kriterium: Zitier-Präzision > Verweigerungs-
  korrektheit > Latenz.

## Files that matter right now

- `planung.md` — Plan + Entscheidungspunkte (Abschnitt 12) + Stand.
- `.agents/skills/pv-rag-agent/SKILL.md` — verbindliche Regeln.
- `agent/README.md` — Betrieb, Konfiguration, Host-Schritte.
- `agent/eval/goldset.yaml` — Goldset (IDs gegen kb.json verifiziert).
- `agent/generate.py` — Grounding-Kern (Prompt, Post-Validierung).
- `wissensbasis/README.md` — Layer-2-Schema (unverändert gültig).