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.