coding.aiMemory wires Claude Code and OpenCode2 to the central ai-memory server: Nix owns the client config (server URL + bearer token file), the OpenCode MCP entry, and the scope markers (home workspace plus one marker per workspaceDirs entry); activation runs ai-memory's own installers for hooks, the Claude MCP bridge and the skills. The token never lands in a generated file: hooks and the bridge read [auth].bearer_token_file, the OpenCode plugin reads the data-dir auth-token symlink. Pi (and its babysitter profile) are no longer used; LifeOS is being removed from the hosts as well. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
20 KiB
ai-memory Rollout Implementation Plan
For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (
- [ ]) syntax for tracking.
Goal: Ein zentraler, selbst gehosteter ai-memory-Server (aimemory.sh) auf m3-hermes, an den Claude Code + OpenCode2 auf m3-kratos und AZ-LT-NIX sowie Hermes auf m3-hermes deklarativ angebunden sind.
Architecture: Server via Upstream-NixOS-Modul services.ai-memory in nixos-config (m3-hermes), öffentlich über Traefik auf m3-atlas → Netbird. Clients über ein neues Home-Manager-Modul coding.aiMemory in m3ta-home (Hybrid: Nix verwaltet Paket, Env, Marker und OpenCode-MCP; eine Activation ruft ai-memory install-hooks/install-mcp/install-skills auf). Host-Repos liefern pro Host ein agenix-Token und schalten das Modul ein.
Tech Stack: NixOS, Home-Manager, agenix, Traefik, Netbird, ai-memory 3.2.x (github:akitaonrails/ai-memory), hermes-agent NixOS-Modul.
Spec: Die Entscheidungen aus der Grilling-Session vom 2026-10-24 stehen unten unter „Entscheidungen“. Upstream-Doku: geklont unter github.com/akitaonrails/ai-memory → README.md#nixos, nix/nixos-module.nix, docs/install.md (Auth ab Z. ~3590), docs/marker-file.md, docs/support-matrix.md (Hermes-Zeile), docs/llm-providers.md.
Entscheidungen (Spec)
- Es gibt einen Server auf m3-hermes für privat und Arbeit. Getrennt wird nur über Projekte in ai-memory.
- Upstream-Modul
services.ai-memoryals System-Service unter/var/lib/ai-memory. Auf Clients läuft kein Server. - Alle Clients nutzen
https://memory.m3ta.dev(MCP, Hooks, Web-UI). Hermes ist auf demselben Host und nutzthttp://127.0.0.1:<port>. - Ein Bearer-Token pro Host (kratos, AZ-LT-NIX, hermes) als
aim_-API-Key, im Host-Repo mit agenix verschlüsselt. Der Admin-Login für das Web-UI läuft über das Root-Passwort (einmalig per Env). - LLM-Konsolidierung über
openai-compatmit dem privaten z.ai/GLM-Key in einem eigenen Secret, nicht inhermes-env. - Client = Hybrid in m3ta-home: Skills ja, keine
install-instructions-Snippets in CLAUDE.md/AGENTS.md. - Capture-Ausschlüsse:
/run/agenix/**,~/.config/sops/**,~/.ssh/**,**/.env*. - Hermes: Hooks + MCP + Skills deklarativ. Honcho bleibt Memory-Provider. Das Community-Plugin wird nicht genutzt.
- Agents: kratos + AZ-LT-NIX = Claude Code + OpenCode2. m3-hermes = nur Hermes.
- Imperatives Test-Setup auf kratos (User-Unit,
~/.local/share/ai-memory, MCP-Eintrag auf Port 49374) wird ohne Backup entfernt. - Rollout: (1) Server + Traefik → (2) kratos → (3) Hermes → (4) AZ-LT-NIX. Nach jeder Stufe
ai-memory doctor. - Nicht in diesem Plan: Transkript-Backfill (später manuell),
ai-memory-wikisync-Backup (Phase 2).
Global Constraints
- Server-Port:
49374(Upstream-Default), registriert alsai-memoryinhosts/common/ports.nix(nixos-config). - Öffentliche URL:
https://memory.m3ta.dev. Die MCP-URL isthttps://memory.m3ta.dev/mcp. - Netbird-Range für die Firewall:
100.64.0.0/16. m3-hermes hat die Netbird-IP100.81.231.152(wie beim hermes-dashboard-Service inhosts/m3-atlas/services/traefik.nix). - Server-Secrets landen nur in
services.ai-memory.ageSecret, nie insettings(das liegt sonst world-readable im Nix-Store). - Client-Token-Pfad (Default):
/run/agenix/ai-memory-token. Er muss für den jeweiligen User lesbar sein (owner = "m3tam3re"bzw."sascha.koenig"). - Im Client-Modul gibt es keine fest verdrahteten
/home/m3tam3re-Pfade, nurconfig.home.homeDirectory. - Server und Clients müssen dieselbe Major/Minor-Version von ai-memory haben. Clients nutzen
pkgs.llm-agents.ai-memory, der Server das Flake-Input. Bei Abweichung wird der Server perservices.ai-memory.packageauf das llm-agents-Paket umgestellt. gitmuss neben dem Client-Binary im PATH liegen (die Hooks rufen es auf).
Review Focus
- Token-Datei fehlt oder ist nicht lesbar (z.B. Host ohne Secret, erster Switch vor agenix): Die Activation darf nicht fehlschlagen. Sie überspringt mit einer klaren Warnung und schreibt keine Hooks mit leerem Token. Den Test dafür gibt es in Task 4, Step 1.
- Home-Manager überschreibt Dateien, die die Activation geschrieben hat:
~/.config/opencode/opencode.jsonist ein HM-Symlink.install-mcp --client opencode2darf dort nicht schreiben, der MCP-Eintrag läuft überprograms.mcp. Den Test dafür gibt es in Task 4, Step 6. - Server nicht erreichbar (AZ-LT-NIX offline, m3-hermes down): Die Hooks puffern lokal, und die Agents starten trotzdem. Das prüft Task 5, Step 6.
- Port/URL-Drift, wie im Test, bei dem MCP auf 49374 und die Hooks auf 49375 zeigten: Hooks, MCP und
AI_MEMORY_SERVER_URLmüssen aus derselben OptionserverUrlkommen. Das prüftai-memory doctorin Task 5, Step 5. - Secrets im Capture: Ein Agent liest
/run/agenix/*oder.env, und die Inhalte landen im Wiki. Den Test über den Home-Marker gibt es in Task 5, Step 7.
Phase 1: Server (Repo nixos-config)
Task 1: Secrets und Flake-Input für den Server
Files:
- Modify:
nixos-config/flake.nix(Inputai-memory, Modul in die m3-hermes-Module) - Modify:
nixos-config/secrets.nix(neue.age-Einträge) - Create:
nixos-config/secrets/ai-memory-server-env.age - Modify:
nixos-config/hosts/m3-hermes/secrets.nix - Modify:
nixos-config/hosts/common/ports.nix(ai-memory = 49374;)
Interfaces:
-
Produces:
config.age.secrets."ai-memory-server-env"auf m3-hermes.inputs.ai-memorysteht inspecialArgszur Verfügung.config.m3ta.ports.get "ai-memory"liefert49374. -
Step 1: Flake-Input ergänzen:
ai-memory.url = "github:akitaonrails/ai-memory";mitinputs.nixpkgs.follows = "nixpkgs".ai-memory.nixosModules.defaultkommt nur in die Modulliste von m3-hermes. -
Step 2: Secret-Datei anlegen (
agenix -e secrets/ai-memory-server-env.age, publicKeys =[m3-hermes] ++ users) mit:AI_MEMORY_AUTH_TOKEN=<openssl rand -hex 32> # Root-Bearer (Admin-CLI, nie an Clients) AI_MEMORY_AUTH__TOKEN_PEPPER=<openssl rand -hex 32> # nötig für aim_-API-Keys AI_MEMORY_AUTH__RECOVERY_TOKEN=<openssl rand -hex 32> AI_MEMORY_AUTH__INITIAL_ROOT_PASSWORD=<≥12 Zeichen, nur beim ersten Start genutzt> AI_MEMORY_AUTH__SECURE_COOKIE=true AI_MEMORY_AUTH__TRUSTED_PROXY_CIDRS=100.64.0.0/16 AI_MEMORY_LLM_PROVIDER=openai-compat AI_MEMORY_LLM_BASE_URL=https://api.z.ai/api/coding/paas/v4 AI_MEMORY_LLM_MODEL=glm-5.3-flash LLM_API_KEY=<privater z.ai-Key>Ob die Env-Namen
AI_MEMORY_AUTH__TOKEN_PEPPERbzw.__BEARER_TOKENstimmen, wird gegennix/nixos-module.nix(secretKeysInSettings) unddocs/install.mdgeprüft, bevor das Secret verschlüsselt wird. -
Step 3: Eval prüfen Run:
nix eval .#nixosConfigurations.m3-hermes.config.age.secrets.ai-memory-server-env.pathExpected:"/run/agenix/ai-memory-server-env" -
Step 4: Commit
feat(m3-hermes): add ai-memory input, ports and server secret
Task 2: ai-memory-Server auf m3-hermes
Files:
- Create:
nixos-config/hosts/m3-hermes/services/ai-memory.nix - Modify:
nixos-config/hosts/m3-hermes/services/default.nix(Import)
Interfaces:
-
Consumes: Task 1 (Secret, Port, Modul)
-
Produces: Server lauscht auf
0.0.0.0:49374. Die Firewall lässt den Port nur aus100.64.0.0/16durch, Loopback ist für Hermes offen. -
Step 1: Modul schreiben im Stil von
hermes-dashboard.nix(let-Block fürnetbirdRange/port):services.ai-memory = { enable = true; bind = "0.0.0.0"; port = config.m3ta.ports.get "ai-memory"; enableWeb = true; ageSecret = "ai-memory-server-env"; openFirewall = false; settings.allowed_hosts = ["memory.m3ta.dev" "localhost" "127.0.0.1" "::1"]; }networking.firewall.extraCommands:ip46tables -A nixos-fw -p tcp --dport <port> -s 100.64.0.0/16 -j nixos-fw-accept
-
Step 2: Bauen Run:
nix build .#nixosConfigurations.m3-hermes.config.system.build.toplevelExpected: Build ok, ohne Assertion zu Secret-Quellen bei Non-Loopback-Bind. -
Step 3: Deployen und Health prüfen (auf m3-hermes) Run:
systemctl is-active ai-memory && curl -s http://127.0.0.1:49374/healthzExpected:activeund{"status":"ok"} -
Step 4: Root-Passwort ändern und Bootstrap-Secret entfernen: Einmal einloggen (das erzwingt den Passwortwechsel). Danach
AI_MEMORY_AUTH__INITIAL_ROOT_PASSWORDaus dem Secret löschen, neu verschlüsseln und deployen. -
Step 5: Commit
feat(m3-hermes): run ai-memory server
Task 3: Traefik-Route memory.m3ta.dev und Host-Tokens
Files:
- Create:
nixos-config/hosts/m3-atlas/services/ai-memory.nix(Muster:vaultwarden.nix, alsoservices.traefik.dynamicConfigOptions.http.{services,routers}.ai-memory) - Modify:
nixos-config/hosts/m3-atlas/services/default.nix
Interfaces:
-
Consumes: Task 2 (Server auf
100.81.231.152:49374) -
Produces:
https://memory.m3ta.devsowie dreiaim_-Keys (kratos,az-lt-nix,hermes), die vorerst nur im Passwortmanager liegen und in Task 5/6/7 in agenix kommen. -
Step 1: Route anlegen:
services.ai-memory.loadBalancer.servers = [{url = "http://100.81.231.152:49374";}]undrouters.ai-memory = { rule = "Host(\memory.m3ta.dev`)"; tls.certResolver = "godaddy"; service = "ai-memory"; entrypoints = "websecure"; }. Der DNS-Eintragmemory.m3ta.dev` → m3-atlas wird gesetzt. -
Step 2: Von außen prüfen (von einem Gerät außerhalb von Netbird) Run:
curl -s https://memory.m3ta.dev/healthz; curl -s -o /dev/null -w '%{http_code}\n' https://memory.m3ta.dev/mcpExpected:{"status":"ok"}und401(ohne Token kein Zugriff) -
Step 3: Host-Keys erzeugen (auf m3-hermes, als Service-User mit Root-Bearer): Run:
for h in kratos az-lt-nix hermes; do sudo -u ai-memory ai-memory --data-dir /var/lib/ai-memory api-key add --username root --label $h; doneExpected: dreiaim_…-Tokens, einmalig angezeigt und sofort sicher abgelegt. -
Step 4: Web-UI prüfen:
https://memory.m3ta.dev/web→ Login als Root funktioniert, und das Cookie trägt dasSecure-Flag. -
Step 5: Commit
feat(m3-atlas): route memory.m3ta.dev to ai-memory
Phase 2: Client-Modul (Repo m3ta-home)
Task 4: Home-Manager-Modul coding.aiMemory
Files:
- Create:
m3ta-home/profiles/sets/coding/agents/ai-memory.nix - Modify:
m3ta-home/profiles/sets/coding/agents/agents.nix(Import ergänzen,llm-agents.ai-memoryaushome.packagesentfernen; das Paket kommt jetzt aus dem Modul) - Test:
m3ta-home/profiles/sets/coding/agents/ai-memory.test.sh(Eval-Checks gegen eine Test-HM-Konfiguration bzw. eine bestehendehomeConfigurations-Ausgabe)
Interfaces:
-
Produces (Optionen, die die Host-Repos setzen):
coding.aiMemory.enable : bool(defaultfalse)coding.aiMemory.serverUrl : str(default"https://memory.m3ta.dev")coding.aiMemory.tokenFile : str(default"/run/agenix/ai-memory-token")coding.aiMemory.agents : listOf (enum ["claude-code" "opencode2"])(default["claude-code" "opencode2"])coding.aiMemory.ignorePaths : listOf str(default["/run/agenix/**" "~/.config/sops/**" "~/.ssh/**" "**/.env*"])
-
Step 1: Failing Eval-Test schreiben (
ai-memory.test.sh, nutztnix evalgegen eine Konfiguration mitcoding.aiMemory.enable = true). Er prüft:home.sessionVariables.AI_MEMORY_SERVER_URL == "https://memory.m3ta.dev"programs.mcp.servers.ai-memory.command == "bash", undargsenthältmcp-bridge --no-session-id --server-url https://memory.m3ta.dev/mcpsowie$(cat /run/agenix/ai-memory-token)home.file.".ai-memory.toml".textenthält[capture]und alle vierignorePathshome.activation ? aiMemoryInstall- Activation-Skript: Bei fehlender Token-Datei steht
ai-memory: token file … missing, skippingauf stderr und der Exit-Code ist 0. Getestet wird mit dem extrahierten Skript,tokenFilezeigt auf einen nicht existierenden Pfad, undai-memoryist per PATH-Stub ersetzt.
-
Step 2: Test laufen lassen Run:
bash profiles/sets/coding/agents/ai-memory.test.shExpected: FAIL (Optioncoding.aiMemoryexistiert nicht) -
Step 3: Modul implementieren (Stil wie
packages.nix:cfg = config.coding.aiMemory,mkEnableOption,mkIf):home.packages = [pkgs.llm-agents.ai-memory pkgs.git]home.sessionVariables.AI_MEMORY_SERVER_URL = cfg.serverUrlprograms.mcp.servers.ai-memorynach dem Muster desexa-Eintrags:bash -c "AI_MEMORY_AUTH_TOKEN=$(cat <tokenFile>) exec ai-memory mcp-bridge --no-session-id --server-url <serverUrl>/mcp". OpenCode2 übernimmt das überenableMcpIntegration.home.file.".ai-memory.toml".textmit[capture]undignore_paths = [...](der Home-Marker gilt für alles unterhalb von$HOMEohne eigenen Marker)home.activation.aiMemoryInstall = lib.hm.dag.entryAfter ["writeBoundary" "claudeSkillsSync"]. Das Skript macht Folgendes:- Ist
tokenFilenicht lesbar: Warnung auf stderr undreturn 0. tok=$(cat tokenFile)- Für jeden Agent in
cfg.agents:$DRY_RUN_CMD ai-memory install-hooks --agent <agent> --apply --server-url <serverUrl> --auth-token "$tok" - Falls
claude-codeinagentssteht:claude mcp remove ai-memory -s user || trueund danachai-memory install-mcp --client claude-code --apply --server-url <serverUrl>/mcp --auth-token "$tok"(session-aware Bridge) ai-memory install-skills --scope global --apply. Die Skills landen in~/.agents/skills, undclaude-skills-syncspiegelt sie.
- Ist
- Kein
install-mcp --client opencode2(sonst Konflikt mit dem HM-Symlinkopencode.json), keininstall-instructions.
-
Step 4: Test laufen lassen Run:
bash profiles/sets/coding/agents/ai-memory.test.shExpected: PASS -
Step 5: Ob die Flags stimmen, gegen die installierte Version prüfen Run:
ai-memory install-skills --help; ai-memory install-mcp --help | grep -A3 auth-tokenExpected:--scope global,--applyund--auth-tokengibt es. Sonst wird Step 3 an die echten Flags angepasst. -
Step 6: HM-Konflikt-Check (Review Focus #2) Run:
nix evalaufxdg.configFile."opencode/opencode.json".textder Test-Konfiguration und dort nachai-memorygreppen Expected: Eintrag vorhanden (kommt ausprograms.mcp), und die Activation enthält keininstall-mcp --client opencode. -
Step 7: Commit
feat(coding): add ai-memory client module
Phase 3: Rollout
Task 5: m3-kratos anbinden (Repo nixos-config)
Files:
- Create:
nixos-config/secrets/ai-memory-token-kratos.age(Inhalt: deraim_-Keykratosaus Task 3) - Modify:
nixos-config/secrets.nix,nixos-config/hosts/m3-kratos/secrets.nix(ai-memory-token = { file = ../../secrets/ai-memory-token-kratos.age; owner = "m3tam3re"; };) - Modify:
nixos-config/hosts/common/users/m3tam3re.nix(in den kratos-hostFlagsden Eintragcoding.aiMemory.enable = true;setzen) - Modify:
nixos-config/flake.lock(nix flake update m3ta-home)
Interfaces:
-
Consumes: Task 3 (Key
kratos), Task 4 (coding.aiMemory) -
Step 1: Imperatives Test-Setup abräumen (auf kratos, einmalig):
systemctl --user disable --now ai-memory.service rm ~/.config/systemd/user/ai-memory.service && systemctl --user daemon-reload claude mcp remove ai-memory -s user rm -rf ~/.local/share/ai-memory ~/.config/opencode/plugins/ai-memory-opencode2.tsDie Hook-Einträge in
~/.claude/settings.jsonüberschreibtinstall-hooks --applyin Step 3. Danach prüfen, dass keine Einträge mit127.0.0.1:49375übrig sind. -
Step 2: Secret + Flag + Lock, dann
nix build .#nixosConfigurations.m3-kratos.config.system.build.toplevel. Expected: Build ok. -
Step 3: Switch Run:
sudo nixos-rebuild switch --flake .#m3-kratosExpected: In der Activation-Ausgabe steht keineskipping-Warnung. -
Step 4: Kein Drift Run:
grep -c 'memory.m3ta.dev' ~/.claude/settings.json; grep -c '4937[45]' ~/.claude/settings.json ~/.claude.jsonExpected: >0 bzw.0 -
Step 5: Doctor Run:
cd ~/p/NIX/m3ta-home && ai-memory doctorExpected: Server erreichbar, Auth ok. Nach einer kurzen Claude-Code- und einer OpenCode2-Session: beide Harnesses haben Sessions erfasst. -
Step 6: Offline-Verhalten (Review Focus #3):
sudo systemctl stop ai-memoryauf m3-hermes. Danach in Claude Code einen Prompt absetzen. Expected: Die Session startet ohne Fehler, und~/.local/share/ai-memory/hook-spoolwächst. Nach dem Neustart des Servers sind die Events nachgeliefert (ai-memory doctor). -
Step 7: Ausschluss-Check (Review Focus #5): In Claude Code
cat /run/agenix/exa-keyausführen lassen. Expected:ai-memory hook --check-capturebzw. die Session-Seite im Web-UI enthält weder den Befehl noch den Inhalt. -
Step 8: Commit
feat(m3-kratos): enable ai-memory client
Task 6: Hermes anbinden (Repo nixos-config)
Files:
- Create:
nixos-config/secrets/ai-memory-hermes-env.age(Inhalt:AI_MEMORY_AUTH_TOKEN=<aim_ hermes>) - Modify:
nixos-config/hosts/m3-hermes/secrets.nix,nixos-config/secrets.nix - Modify:
nixos-config/hosts/m3-hermes/services/hermes-agent.nix
Interfaces:
-
Consumes: Task 2 (Server auf Loopback), Task 3 (Key
hermes) -
Step 1: Snippets erzeugen (auf m3-hermes): Run:
ai-memory install-hooks --agent hermes --server-url http://127.0.0.1:49374; ai-memory install-mcp --client hermes --server-url http://127.0.0.1:49374/mcpExpected: YAML-Blöckehooks:(sechs Events) undmcp_servers:. Diese werden 1:1 als Nix-Attrsets übernommen. -
Step 2: Einbauen in
services.hermes-agent:environmentFilesumconfig.age.secrets."ai-memory-hermes-env".pathergänzenextraPackagesuminputs.ai-memory.packages.${pkgs.stdenv.hostPlatform.system}.defaultergänzen (gleiche Version wie der Server)settings.hooks = <aus Step 1>,settings.hooks_auto_accept = truesettings.mcp_servers.ai-memory = <aus Step 1>(Bridge mit--no-session-id, ohne Token in der Datei)settings.memory.providerbleibt"honcho"
-
Step 3: Skills installieren: ein
systemd.services.hermes-ai-memory-skills(oneshot,User = "hermes",HOME=/var/lib/hermes,HERMES_HOME=/var/lib/hermes/.hermes,before = ["hermes-agent.service"]), dasai-memory install-skills --scope global --agent hermes --applyausführt. -
Step 4: Bauen + Switch, dann: Run:
grep -A2 'ai-memory' /var/lib/hermes/.hermes/config.yaml | head; ls /var/lib/hermes/.hermes/skills | grep ai-memoryExpected: Hooks und MCP-Eintrag stehen in der Datei, die Skills sind vorhanden. -
Step 5: End-to-End-Test (laut Doku von Upstream noch nicht verifiziert): Hermes über das Gateway eine kleine Aufgabe machen lassen, z.B. ein Repo listen, und danach
/new. Expected: Im Web-UI erscheint eine Hermes-Session mit Prompt und Tool-Calls. Bei der nächsten Session bekommt Hermes überpre_llm_callden Handoff. Läuft das nicht, Abweichungen dokumentieren und im Upstream-Issue-Tracker melden. -
Step 6: Commit
feat(m3-hermes): wire hermes-agent into ai-memory
Task 7: AZ-LT-NIX anbinden (Repo AZ-NIX-CLIENTS)
Files:
- Create:
secrets/ai-memory-token.age(publicKeys[AZ-LT-NIX sascha.koenig], Inhalt: deraim_-Keyaz-lt-nix) - Modify:
secrets.nix,hosts/AZ-LT-NIX/secrets.nix(ai-memory-token = { file = ../../secrets/ai-memory-token.age; owner = "sascha.koenig"; };) - Modify:
hosts/common/users/sascha.koenig.nix(in den AZ-LT-NIX-hostFlagsuntercodingden EintragaiMemory.enable = true;setzen) - Modify:
flake.lock(nix flake update m3ta-home)
Interfaces:
-
Consumes: Task 3 (Key
az-lt-nix), Task 4 (coding.aiMemory) -
Step 1: Secret + Flag + Lock, dann
nix build .#nixosConfigurations.AZ-LT-NIX.config.system.build.toplevel. Expected: Build ok. -
Step 2: Switch auf AZ-LT-NIX, ohne dass das private Netbird verbunden ist.
-
Step 3: Doctor in einem Arbeits-Repo Run:
ai-memory doctorExpected:https://memory.m3ta.devist erreichbar, und Claude-Code- sowie OpenCode2-Sessions werden erfasst. Der Projektname im Web-UI ist ein anderer als bei den privaten Repos. -
Step 4: Pfade prüfen Run:
grep -c '/home/m3tam3re' ~/.claude/settings.json ~/.config/opencode/plugins/ai-memory-opencode2.tsExpected:0 -
Step 5: Commit + Push
feat(AZ-LT-NIX): enable ai-memory client