docs(ai-memory): step-by-step rollout for AZ-LT-NIX

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
m3tam3reandClaude Fable 5.1 committed 2026-10-25 13:58:51 +01:00
1 parent 963351200c
commit 3c2fc56c43
1 file changed
+125
+125
View File
@@ -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 <AZ-LT-NIX> -r <sascha.koenig>` in
`secrets/ai-memory-token.age` schreiben, switchen.