From 3c2fc56c43cea0ef0f143cfb971690079254ade5 Mon Sep 17 00:00:00 2001
From: m3tam3re
Date: Sun, 25 Oct 2026 13:58:51 +0100
Subject: [PATCH] docs(ai-memory): step-by-step rollout for AZ-LT-NIX
Co-Authored-By: Claude Fable 5.1
---
docs/ai-memory/az-lt-nix-rollout.md | 125 ++++++++++++++++++++++++++++
1 file changed, 125 insertions(+)
create mode 100644 docs/ai-memory/az-lt-nix-rollout.md
diff --git a/docs/ai-memory/az-lt-nix-rollout.md b/docs/ai-memory/az-lt-nix-rollout.md
new file mode 100644
index 0000000..bc1c7de
--- /dev/null
+++ b/docs/ai-memory/az-lt-nix-rollout.md
@@ -0,0 +1,125 @@
+# ai-memory auf AZ-LT-NIX anbinden
+
+Schritt-für-Schritt-Anleitung, um die Arbeits-Workstation an den zentralen
+ai-memory-Server (`https://memory.m3ta.dev`, läuft auf m3-hermes) anzubinden.
+Alles auf AZ-LT-NIX landet im Workspace `az`.
+
+Voraussetzungen, die bereits erledigt sind:
+
+- Server, Traefik-Route und der Nutzer `sascha` existieren.
+- Der `aim_`-Key mit Label `az-lt-nix` ist ausgestellt und liegt verschlüsselt
+ (für den Host-Key von AZ-LT-NIX und den Benutzer-Key `sascha.koenig`) im
+ Patch unten.
+- m3ta-home `master` enthält das Modul `coding.aiMemory` (ab Commit `9633512`).
+
+## 1. Patch auf AZ-LT-NIX holen
+
+Der Patch liegt auf m3-kratos unter
+`/home/m3tam3re/p/AZ/0001-feat-AZ-LT-NIX-enable-ai-memory-client.patch`.
+Er enthält die vier Änderungen (`secrets.nix`, `hosts/AZ-LT-NIX/secrets.nix`,
+`hosts/common/users/sascha.koenig.nix`, `secrets/ai-memory-token.age`) und
+wurde mit `--binary` erzeugt, damit die `.age`-Datei byteidentisch ankommt.
+
+```bash
+# auf AZ-LT-NIX, in einem leeren Verzeichnis oder dem Repo-Ordner
+scp m3-kratos:/home/m3tam3re/p/AZ/0001-feat-AZ-LT-NIX-enable-ai-memory-client.patch .
+```
+
+## 2. Patch anwenden
+
+```bash
+cd ~/p/NIX/AZ-NIX-CLIENTS # oder wo das Repo liegt
+git checkout master && git pull --ff-only
+git am ../0001-feat-AZ-LT-NIX-enable-ai-memory-client.patch
+```
+
+Erwartet: ein neuer Commit `feat(AZ-LT-NIX): enable ai-memory client`.
+
+Gegencheck, dass das Secret für diesen Host lesbar ist:
+
+```bash
+age -d -i ~/.ssh/sascha.koenig secrets/ai-memory-token.age | cut -c1-4
+```
+
+Erwartet: `aim_`.
+
+## 3. m3ta-home auf den aktuellen Stand ziehen
+
+```bash
+nix flake update m3ta-home
+git add flake.lock
+git commit -m "chore: bump m3ta-home (ai-memory client)"
+```
+
+Der Lock muss mindestens auf m3ta-home `9633512` zeigen. Wenn der Pull über
+SSH nach `code.m3ta.dev` scheitert, den Flake-Input vorübergehend auf
+`git+https://code.m3ta.dev/m3tam3re/m3ta-home` stellen.
+
+## 4. Bauen und switchen
+
+```bash
+nix build .#nixosConfigurations.AZ-LT-NIX.config.system.build.toplevel
+sudo nixos-rebuild switch --flake .#AZ-LT-NIX
+```
+
+In der Activation-Ausgabe darf **keine** Zeile
+`ai-memory: token file /run/agenix/ai-memory-token missing, skipping`
+stehen. Steht sie da, hat agenix das Secret nicht entschlüsselt (Host-Key
+prüfen: `ssh-keyscan -t ed25519 localhost` gegen `secrets.nix`).
+
+## 5. Prüfen
+
+```bash
+# Token und Client-Config
+ls -la /run/agenix/ai-memory-token ~/.local/share/ai-memory/auth-token
+cat ~/.local/share/ai-memory/config.toml # server_url + bearer_token_file
+cat ~/.ai-memory.toml # workspace = "az"
+
+# Claude Code: Hooks zeigen auf den Server, MCP ist die stdio-Bridge
+grep -c 'memory.m3ta.dev' ~/.claude/settings.json # > 0
+claude mcp get ai-memory # Status: Connected, Type: stdio
+
+# OpenCode: Plugin und MCP-Eintrag
+grep -o 'const SERVER = "[^"]*"' ~/.config/opencode/plugins/ai-memory-opencode2.ts
+grep -A4 '"ai-memory"' ~/.config/opencode/opencode.json
+```
+
+Dann eine kurze Claude-Code-Session und eine OpenCode-Session in einem
+Arbeits-Repo starten und wieder beenden. Danach von kratos aus:
+
+```bash
+ai-memory list-projects
+```
+
+Erwartet: das Repo erscheint im Workspace `az`.
+
+## 6. Pushen
+
+```bash
+git push origin master
+```
+
+## Was das Modul auf dem Host macht
+
+- Nix schreibt `~/.local/share/ai-memory/config.toml` (Server-URL,
+ `bearer_token_file = /run/agenix/ai-memory-token`), den MCP-Eintrag in
+ `opencode.json` und den Marker `~/.ai-memory.toml` mit `workspace = "az"`
+ plus den Capture-Ausschlüssen.
+- Die Activation verlinkt `~/.local/share/ai-memory/auth-token` auf das
+ Secret (das OpenCode-Plugin liest diesen Pfad), ruft
+ `ai-memory install-hooks` für Claude Code und OpenCode2 auf, registriert
+ für Claude Code die session-aware stdio-Bridge und installiert die Skills
+ nach `~/.agents/skills`.
+- Der Token steht in keiner generierten Datei. Hooks und Bridge lesen ihn aus
+ der Client-Config.
+
+## Bekannte Grenzen
+
+- `ai-memory doctor`, `recent` und `search` im Terminal brauchen den
+ Root-Bearer und antworten mit dem Host-Key `403`. Agents über MCP sind
+ nicht betroffen.
+- Ist der Server nicht erreichbar, puffern die Hooks lokal in
+ `~/.local/share/ai-memory/hook-spool` und liefern nach.
+- Key rotieren: auf m3-hermes `ai-memory api-key rotate` für Label
+ `az-lt-nix`, neuen Wert mit `age -r -r ` in
+ `secrets/ai-memory-token.age` schreiben, switchen.