memory/concepts/memory-layer-architecture.md

title, category, tags, created, modified

title	category	tags	created	modified
Memory Layer Architecture	concepts	memory architecture hindsight lcm wiki separation	2026-09-27	2026-09-27

Memory Layer Architecture — Practical Rules

Übersicht

7 Schichten mit klaren, nicht-überlappenden Rollen.

#	Layer	System	Pfad/Ort	Rolle	Wann nutzen
L0	Hot	MEMORY.md + USER.md	~/.hermes/memories/	System-Prompt Injection, komprimierte Facts	Jede Session (automatisch)
L1	Curated	LLM Wiki	~/.hermes/memory/	Browsbares Wissen, git-synced	Wenn Details gebraucht werden
L2	Semantic	Hindsight	K8s PostgreSQL	Vektor-Suche, semantisches Retrieval	Cross-Session Lookup
L3	Procedural	Skills	~/.hermes/skills/	Wie-geht-es Prozeduren mit Pitfalls	Bei wiederkehrenden Tasks
L4	Episodic	LCM + session_search	SQLite lcm.db / state.db	Rohe Gesprächsverläufe, Compaction	Innerhalb aktiver Session
L5	Solutions	Solution Docs	~/docs/solutions/	Problem-Lösungs-Paare	Nach substanziellen Tasks
L6	Project	AGENTS.md	pro Repo	Repo-spezifische Konventionen	Beim Arbeiten in einem Repo

Was wohin gehört — Entscheidungsbaum

Ist es ein Fact über Dominik persönlich?
  → USER.md (L0)
  Ist es sein Kommunikationsstil, Safety-Rule, oder Workflow-Präferenz?
    → USER.md
  Ist es ein persönlicher Umstand (Größe, Gewicht, Arbeitgeber)?
    → Hindsight (L2) — NICHT USER.md

Ist es ein Infra-Fakt (IP, Version, Konfiguration)?
  → LLM Wiki (L1) — systems/ oder reference/
  Braucht er jede Session sofort?
    → MEMORY.md (L0) als 1-Zeiliger Pointer "→Wiki systems/xyz"

Ist es ein "Wie mache ich X"-Prozess?
  → Skills (L3)

Ist es ein "Wir hatten Problem Y, Lösung war Z"-Eintrag?
  → Solution Doc (L5) + Hindsight-Index (L2)

Ist es ein vergangenes Gesprächsereignis?
  → LCM (L4) kümmert sich automatisch darum

L0 — MEMORY.md vs USER.md

USER.md (1.375 chars max)

Nur: Dominiks Persönliche Präferenzen, Safety-Rules, Kommunikationsstil

• "NIEMALS ohne Approval löschen"
• "Action-first, kein Dom"
• "Crash+Alert statt Silent Skip"
• "Laya in Sessions nutzen"

NICHT: Infra-Fakten, IP-Adressen, Versionsnummern, Team-Struktur

MEMORY.md (2.200 chars max)

Nur: Komprimierte Pointer auf Wiki-Seiten + nicht-wikiffähige Quick-Facts

• Frigate v0.18 CT151. →Wiki systems/frigate
• Galera:VM300/301/302,VIP .70. →Wiki systems/galera-maxscale
• Baufinanz-Zahlen (persönlich, nicht im Wiki)
• LinkedIn Persona (Workflow, nicht im Wiki)

NICHT: Vollständige Specs, Konfigurationsdetails, lange Beschreibungen

L1 — LLM Wiki

Wann erstellen/aktualisieren?

• Bei jeder infrastrukturellen Änderung (Compound-Learning Cycle Phase 4.7)
• Neue Seite wenn: neues System, neuer Service, neue architektonische Entscheidung
• Patch wenn: Versionswechsel, IP-Änderung, Known Issue hinzugekommen

Wann NICHT?

• Procedures → Skills (L3)
• Problem-Solution Pairs → Solution Docs (L5)
• Credentials → 1Password

L2 — Hindsight

Was gehört rein?

• Semantische Pointer auf Solution Docs und wichtige Meilensteine
• Cross-Session Kontext der nicht im Wiki steht (z.B. "wir haben am Datum X entschieden...")
• Episodisches Wissen über Projekte, Entscheidungen, Learnings

Was NICHT rein gehört?

• ❌ Infra-Topologie (→ L1 Wiki)
• ❌ Aktuelle IPs/Versionsnummern (→ L1 Wiki, werden schnell stale)
• ❌ Procedures (→ L3 Skills)
• ❌ Credentials (→ 1Password)
• ❌ Session-Fortschritt (→ L4 LCM)

Bekanntes Problem: Hindsight Accumulation

Hindsight hat über Monate Infra-Fakten angesammelt die inzwischen teilweise veraltet sind (9 vs 8 Nodes, alte OSD-Counts). Hindsight bietet keine Delete-Funktion via Tools. Strategie:

1. Zukünftig nur noch semantische Pointer + Entscheidungen speichern
2. Topologie-Fakten nicht mehr via hindsight_retain ablegen
3. Veraltete Einträge ignorieren — Hindsight Ranking bevorzugt neuere Memories

L4 — LCM (Local Conversation Memory)

Rolle

• Innerhalb aktiver Session: Compaction, Summary-DAG, Fresh Tail
• Cross-Session (lcm.db): Rohe Nachrichten + Summary Nodes aller Sessions
• Kein manuelles Management nötig — läuft automatisch

Wann manuell eingreifen?

• lcm_status bei Verdacht auf Compression-Problemen
• lcm_grep um exakte Phrasen in vergangenen Sessions zu finden
• lcm_recall für bedeutungsbasierte Cross-Session-Suche
• Niemals manuell Daten in LCM schreiben — es ist Auto-Managed

L5 — Solution Docs

Wann erstellen?

• Nach substanziellem Bugfix (≥5 Tool-Calls)
• Nach Architektur-Änderung
• Nach komplexer Migration
• Nach schwierigem Troubleshooting

Format

~/docs/solutions/{type}/{YYYY-MM-DD}-{slug}.md Types: architecture/, bugfix/, migration/, workflow/

Immer: Hindsight-Index (hindsight_retain) nach Erstellung

Related

• systems/hindsight — Hindsight Setup, API
• systems/laya — Laya Classifier
• Skill: memory-sync — Wiki Maintenance Protocol
• Skill: software-development/compound-learning — Phase 4.7 Wiki Update