# Memory-MCP-Knowledge: Nutzungsregeln & Lernprotokoll

> **Zweck:** Dieses Dokument bündelt die Regeln und das Lernprotokoll für den Betrieb eines sitzungsübergreifenden Memory-MCP-Servers im täglichen Agentenbetrieb. Es ist für jeden KI-Agenten (Qwen Code, Kimi Code, Claude Code u. a.) geschrieben — damit du nicht dieselben Umwege nehmen musst. Es ergänzt das Setup-Paket (`memory-mcp-setup.zip`) um den Teil, der am längsten gedauert hat: **wann man liest, wann man schreibt, und wie die Regeln entstanden sind.**
>
> **Stand:** 2026-09-03
> **Quelle:** Michael Logies, rund 3 Wochen täglicher Praxisbetrieb mit einem lokalen Memory-MCP-Server (SQLite + sqlite-vec + FTS5 + ONNX-Embeddings).
> **Lizenz:** CC0 — frei verwendbar, ohne Namensnennung.

---

## 1. Der Server in einem Absatz

Ein schlanker, vollständig offline laufender MCP-Server (`memory_store`, `memory_update`, `memory_search`, `memory_get`, `memory_recent`, `memory_delete`, `memory_status`) auf SQLite-Basis mit sqlite-vec (Vektorsuche) und FTS5 (BM25-Volltext), fusioniert über Reciprocal Rank Fusion (RRF, K=60). Embeddings: quantisiertes `Xenova/multilingual-e5-small` ONNX (112,8 MB, 384 Dimensionen), CPU-only. Query-Präfix `query: `, Passage-Präfix `passage: `. Temporal Decay ist **deaktiviert** (λ=0) — die Begründung steht in §4. Setup: `memory-mcp-setup.zip` auf derselben Seite.

---

## 2. Die Nutzungsregeln (der Kern)

Diese Regeln sind das destillierte Ergebnis des täglichen Betriebs. Sie sind bewusst hart formuliert — jede einzelne existiert, weil ihr Fehlen einen echten Fehler verursacht hat.

### R1 — Memory-first: erst suchen, dann denken

**Rufe `memory_search` als ersten Schritt bei jeder Frage oder Aufgabe auf — bevor ein Gedanke zu Ende gedacht, bevor geantwortet, bevor gehandelt wird.** Verlasse dich nicht zuerst auf allgemeines Wissen oder Intuition; im Memory liegen geprüfte, erfahrungsbasierte Workflows. Allgemeines Wissen ist nur Rückfall, wenn das Memory nichts findet.

*Warum diese Regel absolut ist:* In der weicheren Fassung („prüfe das Memory, wenn es relevant ist") hat der Agent wiederholt Workflows neu erfunden und alte Fehler wiederholt (z. B. `readfile()` auf einer SQLite-Datenbank mit BLOBs statt des gemerkten parameterized-query-Workflows, ein verbotenes destruktives Index-Rebuild vorgeschlagen, deaktivierte Plugins als aktiv gelistet). Die Regel wurde nach jedem dieser Vorfälle zur „keine Ausnahme"-Fassung verschärft.

### R2 — Speichern nach jeder wissenserweiternden Aktion

Nach jeder abgeschlossenen Aufgabe mit neuem Wissen (neue Regel, neue Datei, neuer Workflow, gefundener Fehler, bestätigter Ansatz, Nutzerkorrektur) sofort `memory_store` aufrufen — **auch die scheinbar kleinen Details**. Was heute offensichtlich wirkt, ist in drei Wochen unsichtbar.

### R3 — Vor dem Speichern deduplizieren, aktualisieren statt stapeln

Vor `memory_store`: nach vorhandenen Einträgen zum Thema suchen. Existiert einer und ist veraltet, **überschreiben oder aktualisieren** — niemals Duplikate stapeln. Duplikate vergiften das Ranking und verschwenden beim Abruf Kontext.

### R4 — Vor Arbeitsbeginn gezielt lesen

Vor Beginn einer Aufgabe gezielt nach deren Schlagworten suchen. Nicht auf das verlassen, was der Session-Start-Check zufällig geliefert hat; nach dem *konkreten* Thema suchen (Servernamen, Toolnamen, Workflow-Begriffe).

### R5 — Die Session sauber abschließen

Am Session-Ende die jüngsten Einträge prüfen (`memory_recent`) und nachtragen, was gelernt, aber nie gespeichert wurde.

### R6 — Tag-Disciplin

Jeder Eintrag bekommt Inhalts-Tags **plus** Rollen-Tags: `rolle:forschung` (Recherche/Zotero), `rolle:system` (MCP, Linux, Setup, Tooling), `rolle:web` (Website, Publii, HTML/CSS). Rollen-Tags ermöglichen gezieltes Wiederfinden; Inhalts-Tags ohne Rollen-Tags machen das Memory nur vom Zufall abhängig.

### R7 — Alle Memory-Server beim Session-Start prüfen

Bei jedem Session-Start verifizieren, dass jeder MCP-Server erreichbar und funktionsfähig ist (bei uns: Memory-Server, Zotero-Semantic-Index-Server, Zoteus) — vor der ersten Aufgabe, nicht beim ersten Fehler. Ein mitten in der Aufgabe entdeckter toter Server kostet die ganze Sitzung.

### R8 — Was NICHT gespeichert wird

- **API-Keys, Tokens, Secrets — niemals.** Content-Filter blockieren unter Umständen die komplette Anfrage, wenn ein Key-Muster über das Memory in den Kontext gelangt. Keys gehören ausschließlich in dedizierte Konfigurationsdateien.
- Punkt-in-Zeit-Beobachtungen ohne Datum. Immer mitspeichern, *wann* ein Fakt galt.
- Ephemeren Aufgaben-Zustand, rohe Fehler-Transkripte, alles, was sich aus Code/Repository ableiten lässt.
- Alles, was der Nutzer zu vergessen gebeten hat.

### R9 — Markdown-Dateien bleiben maßgeblich für dauerhafte Regeln

Der Memory-Server ergänzt `AGENTS.md`/`MEMORY.md`/`WORKLOG.md`, er ersetzt sie nicht. Dauerhafte Regeln und technische Details stehen zusätzlich in den Markdown-Dateien; im Zweifel **doppelt speichern**. Das Memory gewinnt bei halbstrukturiertem, vorfallgetriebenem Wissen; Markdown gewinnt bei allem, was auch einen defekten Memory-Server überstehen muss.

### R10 — Reviewen statt horten

Quartalsweise: Einträge prüfen, veraltete löschen oder aktualisieren. Überholtes Wissen, das gut rankt, ist schlimmer als fehlendes Wissen — es führt aktiv in die Irre.

---

## 3. Was gespeichert wird (und was einen guten Eintrag ausmacht)

Gute Einträge enthalten: **die Regel oder den Fakt**, **das Warum** (den Vorfall oder Grund), **das Wie** (den konkreten Befehl oder Workflow) und **das Datum**. Das „Warum" ermöglicht es einer künftigen Sitzung, Grenzfälle zu beurteilen, statt einer veralteten Regel blind zu folgen.

Gespeichert wird: Workflows, die Iteration gekostet haben; Tool-Eigenheiten und Stolpersteine; Nutzerkorrekturen (die wertvollsten Einträge überhaupt); Reparaturprozeduren; Benchmark-Ergebnisse mit Datum; Entscheidungen samt verworfener Alternativen.

---

## 4. Die Lern-Timeline (wie die Regeln tatsächlich entstanden sind)

Diese Sektion dokumentiert die **festgelegten Lernregeln und ihre Zeitpunkte** — denn die Meta-Lektion lautet: Eine funktionierende Memory-Discipline wird nicht am Reißbrett entworfen; sie konvergiert über Wochen, getrieben von echten Vorfällen.

| Datum | Ereignis | Regel, die daraus entstand |
|---|---|---|
| 09.08.2026 | Server v1 eingerichtet (all-MiniLM-L6-v2, 22-MB-Modell) | Grundregel: relevante Informationen standardmäßig speichern; dauerhafte Regeln zusätzlich in Markdown-Dateien; im Zweifel doppelt speichern |
| 10.08.2026 | Alternativen geprüft (Mem0, reines SQLite, PyTorch — verworfen wegen Cloud-Lock-in, fehlender Semantik bzw. 1,4-GB-Venv) | ONNX-Weg bestätigt; Erwartungen dokumentiert: Memory ergänzt die Markdown-Dateien |
| 15.08.2026 | Erste Pflegeregeln formalisiert | Speichern nach jeder Aufgabe, Suche vor Arbeitsbeginn, `memory_recent` am Session-Ende, WORKLOG.md synchron halten, quartalsweises Review, Rollen-Tags |
| 24.08.2026 | Server v2: `multilingual-e5-small` (112,8 MB), Hybrid-Suche (FTS5 + Vektor + RRF) | Deutsche Queries trafen endlich zuverlässig; exakte Begriffe, Eigennamen und Versionsnummern ohne semantische Nähe findbar |
| 25.08.2026 | **Temporal Decay deaktiviert** (λ=0,005 → 0) | Zeitstabiles Wissen (Berechnungsregeln, Workflows) wurde für sein Alter bestraft. Relevanz kommt jetzt aus dem Hybrid-Ranking; überholtes Wissen wird manuell markiert |
| 26.08.2026 | Session-Start-Checkliste erweitert | ALLE Memory-Server beim Session-Start prüfen — ein in der Checkliste vergessener Server wurde erst bei der ersten Nutzung entdeckt |
| 26.08.2026 | Zwei Zotero-Vorfälle: ein bedingter Löschbefehl („wenn X, dann Y") wurde ohne erfüllte Bedingung ausgeführt; eine unwiderrufliche Löschung erfolgte ohne Rückfrage | Bedingte Anweisungen wörtlich befolgen — „wenn X, dann Y" nur bei nachweislich erfülltem X ausführen, sonst berichten; vor unwiderruflichen Aktionen (Löschen, Überschreiben) immer nachfragen, auch wenn die Bedingung scheinbar erfüllt ist |
| 27.08.2026 | **Memory-first zur absoluten Regel verschärft** | Nach wiederholten Verstößen (neu erfundene Workflows, ignorierte Memory-Regeln): erst suchen, keine Ausnahmen, mit konkreten früheren Verstößen als Negativbeispielen direkt in der Instruction-Datei des Agenten |
| 28.08.2026 | `memory_search`-Absturz behoben (NoneType-Fehler bei Volltext-Treffern), Vector-Repair-Workflow etabliert | Operationale Gotchas erfasst (siehe §5); Benchmark zeigte den reparierten Index in voller Qualität |
| 29.08.2026 | Duplikate im Memory konsolidiert (mehrere Einträge beschrieben dieselbe Regel doppelt); Volltext-Pflicht formuliert | R3 konsequent durchgesetzt: Konsolidieren statt Stapeln wird regelmäßig geprüft; bei Zotero-Recherchen mit vorliegenden Volltexten müssen diese ausgewertet werden — keine Antworten allein aus Abstracts, Suchtreffern oder Vorwissen |
| 30.08.2026 | Zwei Publii-Vorfälle: eine ersetzte Download-Datei wurde nur nach `input/media` kopiert (Publii synchronisiert aber `output/media` → Live-Seite versprach die neue Fassung, der Link lieferte die alte); in einer Anweisung wurde eine Abkürzung über die Website statt über die DB gesucht | Ersetzte Mediendateien gehören in **input, output UND preview** (`media/`-Baum) — Publii synchronisiert `output/media` mit dem Server, nicht `input/media`; Website-Texte werden immer in der DB (`posts.text`) geändert, nie in gerenderten Dateien |
| 31.08.2026 | Notizverlust im Memory (ein Eintrag ging beim Überschreiben verloren) — Reaktion: **stündliche SQLite-Snapshots** (`VACUUM INTO`, nur bei Änderung, 8 Tage Aufbewahrung, unabhängiger Cron) + `verify.sh`-Prüfroutine im Setup-Paket | Nach DB-Updates zuerst Backup, dann schreiben; Memory-Datenbanken werden per `VACUUM INTO` gesichert (konsistenter Snapshot ohne WAL-Falle, kein rohes `cp`); die Prüfroutine (`verify.sh`) meldet venv, Pakete, Modell, DB, Backup-Cron und Speicherplatz als Markdown-Bericht |
| 02.09.2026 | Neuer Eintrag wurde per `memory_store` über einen bestehenden gestapelt, statt ihn zu aktualisieren | Vor dem Schreiben prüfen: `memory_update` statt `memory_store`, wenn ein Eintrag das Thema schon behandelt — content-loses Update ändert nur Tags/Source, Inhaltsänderung re-embeddet |
| 03.09.2026 | **Chunked Embedding:** lange Notizen (v4-Server) werden an Markdown-Grenzen in ≤450-Tokens-Chunks (50 Tokens Überlappung) zerlegt und vollständig embedded; Suche aggregiert Chunk-Treffer pro Notiz | Semantische Treffer tief in langen Notizen sind jetzt sichtbar (vorher: nur die ersten 512 Tokens waren im Vektor vertreten); `memory_status` meldet `chunk_entries` |

**Meta-Lektionen aus der Timeline:**

1. **Regeln ohne dokumentierte Verstöße halten nicht.** Die Memory-first-Regel wurde erst zuverlässig, als vergangene Verstöße als konkrete Negativbeispiele aufgeschrieben wurden.
2. **Jeder Vorfall hat genau eine Regel produziert.** Der Versuch, die ganze Discipline vorab zu definieren, erzeugte Regeln, die ignoriert wurden; aus echten Fehlern geborene Regeln hielten.
3. **Nutzerkorrekturen sind die wertvollsten Einträge.** Jedes „Warum hast du X gemacht statt den gemerkten Weg?" wurde am selben Tag zur dauerhaften Regel.
4. **Das Modell-/Hybrid-Upgrade (v2) war der Wendepunkt für deutsche Inhalte** — vorher wurde das Memory seltener durchsucht, weil ihm weniger vertraut wurde.

---

## 5. Operationale Gotchas (28.8.–3.9.2026, alle in der Praxis erprobt)

- **Reparierter Index:** Nach der Reparatur vektorloser Passagen nur die betroffenen Items neu einbetten — per Tag add+remove „touchen" (Versionsbump) und inkrementell updaten. ~0,25 $ statt ~10 $ für ein Voll-Rebuild.
- **Inkrementelle Updates und Volltext:** Ein Index-Update *ohne* den Volltext-Schalter löscht stillschweigend die Volltext-Passagen der neu verarbeiteten Items (nur Metadaten werden neu gechunkt). Updates für Items mit Anhängen immer mit Volltext-Option fahren.
- **Massen-Tag-/Schreiboperationen:** API-Clients timen bei großen Batches (hunderte Items) aus, obwohl die Writes serverseitig weiterlaufen. Mit einer Zähl-Query verifizieren, idempotent nachziehen, Batches ≤ 300.
- **Write-Stürme → HTTP 502:** kurz zurücklehnen und wiederholen; die Writes sind idempotent.
- **Die Bugklasse „Suche stürzt ab":** Ein einziger fehlerhafter Metadatenwert (z. B. ein `None`, wo eine Zahl erwartet wird) kann die *gesamte* Suche töten. Behoben durch None-sichere Behandlung; reine Volltext-Treffer liefern jetzt eine `null`-Vektordistanz statt eines Absturzes. Wenn die Suche nur bei manchen Queries stirbt: erst nach ungeschützten Typ-Annahmen suchen, bevor man dem Index die Schuld gibt.
- **SQLite-Datenbanken kopieren (2.9.2026, dreifach bestätigt):** rohes `cp` auf eine geöffnete SQLite-DB (WAL-Modus) liefert eine 0-Byte-Datei. Immer `sqlite3 DB "VACUUM INTO '/pfad/backup.db';"` — konsistenter Snapshot, auch im laufenden Betrieb.
- **HTML mit Links in `memory_store`-Inhalten:** unproblematisch; nicht vom Content-Filter abschrecken lassen, URLs stören das Einbetten nicht.

---

## 6. Import in das eigene Setup

1. §2 überfliegen und die Regeln wörtlich übernehmen — sie sind CC0 und agentenagnostisch.
2. Im eigenen Memory-System speichern (ein Eintrag pro Regel oder pro Regelblock), suchbar getaggt.
3. Die Memory-first-Regel und die Verstoßbeispiele in die immer geladene Instruction-Datei des Agenten aufnehmen — das Memory allein reicht nicht, denn die Regel betrifft genau den Moment, in dem das Memory *überhaupt geöffnet* wird.
4. Die Timeline (§4) an die eigenen Vorfälle anpassen: Deine Verstöße werden andere sein, deine Regeln sollten es auch.

*Zusammengestellt von Qwen Code (GLM-5.3-Flash) aus der Memory-Datenbank des Agenten-Setups von Michael Logies. Stand 3.9.2026: 240 Notizen.*