From 2ef79cbc3aef71e5be12e3166860477bbf8d9197 Mon Sep 17 00:00:00 2001 From: KiteStacks Backup Date: Tue, 9 Jun 2026 23:09:57 -0500 Subject: [PATCH] Add Claude Code memory snapshot and restore instructions --- README.md | 22 ++++++++++++++ claude-memory/MEMORY.md | 7 +++++ claude-memory/feedback_tool_confirmation.md | 13 +++++++++ claude-memory/project-cloud-migration.md | 28 ++++++++++++++++++ claude-memory/project-kitestacks.md | 19 ++++++++++++ claude-memory/project-sso.md | 32 +++++++++++++++++++++ claude-memory/user-profile.md | 10 +++++++ 7 files changed, 131 insertions(+) create mode 100644 claude-memory/MEMORY.md create mode 100644 claude-memory/feedback_tool_confirmation.md create mode 100644 claude-memory/project-cloud-migration.md create mode 100644 claude-memory/project-kitestacks.md create mode 100644 claude-memory/project-sso.md create mode 100644 claude-memory/user-profile.md diff --git a/README.md b/README.md index c8b4bde..825dbf6 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,28 @@ Created for migrating the current KiteStacks host to Hetzner Cloud. - `restore/RESTORE.md` - first-pass restore procedure. - `SHA256SUMS` - checksums for all files in this backup. +## Restoring Claude's Context on a New Machine + +This repo includes a snapshot of Claude Code's persistent memory in `claude-memory/` +(taken from `~/.claude/projects/-home-kenpat/memory/` on the original host). It +captures the homelab setup, this migration plan/status, and your working +preferences, so a fresh Claude session on the new machine doesn't start blank. + +To restore it: + +1. Clone this repo on the new machine. +2. Copy the contents of `claude-memory/` into Claude Code's memory directory for + your new home path, e.g.: + ```sh + mkdir -p ~/.claude/projects/-home-/memory + cp claude-memory/*.md ~/.claude/projects/-home-/memory/ + ``` +3. Start a Claude Code session in that project. It will automatically load + `MEMORY.md` and the linked memory files, and can pick up the migration + (and any other tracked work) where it left off. +4. Update `claude-memory/project-cloud-migration.md` as migration phases + progress, and re-copy it back into this repo so future restores stay current. + ## Important This repository contains secrets: `.env` files, tunnel tokens, app database data, and service credentials. Keep it private. diff --git a/claude-memory/MEMORY.md b/claude-memory/MEMORY.md new file mode 100644 index 0000000..d64bb0b --- /dev/null +++ b/claude-memory/MEMORY.md @@ -0,0 +1,7 @@ +# Memory Index + +- [User Profile](user-profile.md) — kenpat, homelab operator, kitestacks.com +- [Project: KiteStacks Homelab](project-kitestacks.md) — Docker Compose homelab, Cloudflare tunnels, autosync to Forgejo +- [Project: Authentik SSO](project-sso.md) — SSO setup in progress; what's done, what's pending +- [Feedback: Tool Confirmation](feedback_tool_confirmation.md) — don't pause for tool confirmation, keep going autonomously +- [Project: Cloud Migration](project-cloud-migration.md) — Phase 1 backup→Forgejo (done), Phase 2 Oracle VPS (planned), LFS/Cloudflare 413 gotcha diff --git a/claude-memory/feedback_tool_confirmation.md b/claude-memory/feedback_tool_confirmation.md new file mode 100644 index 0000000..d75d367 --- /dev/null +++ b/claude-memory/feedback_tool_confirmation.md @@ -0,0 +1,13 @@ +--- +name: feedback_tool_confirmation +description: "User preference: don't pause for tool confirmation — keep going autonomously" +metadata: + node_type: memory + type: feedback + originSessionId: c435573b-6aff-4e43-a184-c17aa96ce348 +--- + +Don't pause and wait for the user to hit enter or confirm tool calls. Keep executing until the task is complete. + +**Why:** User wants uninterrupted autonomous execution. +**How to apply:** Only stop when the user must do something manually (UI action, testing) or when a decision genuinely requires their input. Never pause mid-task just to confirm a command. diff --git a/claude-memory/project-cloud-migration.md b/claude-memory/project-cloud-migration.md new file mode 100644 index 0000000..2156af2 --- /dev/null +++ b/claude-memory/project-cloud-migration.md @@ -0,0 +1,28 @@ +--- +name: project-cloud-migration +description: "KiteStacks server migration plan — Phase 1 (Forgejo backup, restore to new desktop) and Phase 2 (Oracle Cloud VPS, always-on)" +metadata: + node_type: memory + type: project + originSessionId: 1d92780e-77c5-41ac-8887-daca0ea55e8b +--- + +**Phase 1 — STATUS: backup pushed & verified, restore not yet performed** + +Goal: be able to pull the backup repo onto a new (desktop) machine and physically relaunch the homelab from it. + +- Full server backup lives in Forgejo repo `kenpat/kitestacks-cloud-migration` (private), clone url `http://100.90.13.55:3006/kenpat/kitestacks-cloud-migration.git` (also reachable at `gitforge.kitestacks.com` for small files). +- Source backup: `/home/kenpat/kitestacks-cloud` (git repo, 1 commit `6ffcbea`, ~4.3GB). Contains `archives/*.tar.gz` (docker bind-data, syncthing-shared, scripts, host /etc subset), `volume-exports/*.tar.gz` (named Docker volumes), `inventory/`, `restore/RESTORE.md`, `SHA256SUMS`. +- 14 large files (~2.3GB) are tracked via **Git LFS** — required `apt-get install git-lfs` (no passwordless sudo on this host, user ran it manually) and `git lfs migrate import --include="archives/*.tar.gz,volume-exports/*.tar.gz"`. +- **Known gotcha**: Forgejo's public hostname `gitforge.kitestacks.com` (Cloudflare Tunnel) returns HTTP 413 for any LFS object >~100MB. The 3 big files (docker-bind-data.tar.gz ~967MB, kite-ai_open-webui.tar.gz ~963MB, syncthing-shared.tar.gz ~165MB) had to be PUT directly to `http://100.90.13.55:3006/kenpat/kitestacks-cloud-migration.git/info/lfs/objects//` (local Tailscale IP, bypasses Cloudflare). `git lfs pull` for these 3 files will need the same workaround — clone/pull via the local IP, not the public hostname. +- Verified: local HEAD == remote HEAD, all 15/15 LFS objects present server-side with sizes matching `SHA256SUMS` OIDs. +- Documented in `/home/kenpat/forgejo-repos/kitestacks-homelab/docs/KiteStacks-Homelab-Documentation-v1.3.922.md`. + +**Phase 1 remaining work**: actual restore-to-new-desktop has NOT been done/tested yet. When the user pulls a Claude session in on the new desktop, the workflow is: clone `kitestacks-cloud-migration` (via local IP for LFS), follow `restore/RESTORE.md`, restore Docker volumes from `volume-exports/`, restore bind-mounts from `archives/docker-bind-data.tar.gz`, bring stacks up via the compose files, re-point Cloudflare Tunnel. + +**Why**: User wants to migrate the KiteStacks homelab off the current desktop onto new hardware first (Phase 1), then to an always-on Oracle Cloud VPS (Phase 2) so services don't go down when the desktop sleeps/is off. + +**How to apply**: When the user says they're moving to a new desktop / starting the restore, walk through `restore/RESTORE.md` using this memory's notes (especially the LFS/Cloudflare gotcha). Once services are confirmed running on the new desktop, mark Phase 1 complete in this file, notify the user explicitly, and begin Phase 2 (Oracle Cloud VPS setup) — update this file with Phase 2 progress the same way. + +**Phase 2 — STATUS: not started** +Plan: provision an Oracle Cloud VPS, migrate the same stack there for always-on hosting (independent of desktop power state). No infra details yet — to be filled in once started. diff --git a/claude-memory/project-kitestacks.md b/claude-memory/project-kitestacks.md new file mode 100644 index 0000000..e0995db --- /dev/null +++ b/claude-memory/project-kitestacks.md @@ -0,0 +1,19 @@ +--- +name: project-kitestacks +description: "KiteStacks homelab infrastructure — Docker Compose services, networking, autosync, Forgejo repo" +metadata: + node_type: memory + type: project + originSessionId: 301d23e2-6920-42b0-a27d-eba4e667b7f7 +--- + +All services run as Docker Compose stacks in `/home/kenpat/docker//`. +All containers join the `kitestacks` external Docker bridge network (172.18.0.0/16) — cloudflared uses container names as hostnames to route traffic. +Cloudflare Tunnel (token-based) routes `*.kitestacks.com` → containers on the kitestacks network. Tunnel ingress rules are configured in the Cloudflare Zero Trust dashboard (not in local files). + +**Autosync system:** A systemd service (`kitestacks-autosync`) watches `/home/kenpat/docker/` via inotify and pushes any file change to the Forgejo repo `kenpat/kitestacks-homelab` at `gitforge.kitestacks.com`. Working repo lives at `/opt/kitestacks-autosync/kitestacks-homelab/`. User's local clone is at `/home/kenpat/forgejo-repos/kitestacks-homelab/` (remote: `http://100.90.13.55:3006/kenpat/kitestacks-homelab.git`). Both point to the same Forgejo repo. + +**Versioned docs:** Autosync auto-creates `docs/KiteStacks-Homelab-Documentation-v1.3.NNN.md` on each change. Manual/feature docs use the next version number. Current version as of 2026-06-08: 1.3.884. + +**Why:** User always wants changes documented and pushed to Forgejo at the end of any task. +**How to apply:** After making file changes, write docs to `/home/kenpat/forgejo-repos/kitestacks-homelab/docs/`, update CHANGELOG.md and README.md version tag, commit, and push. Use direct IP remote (no TLS issues). diff --git a/claude-memory/project-sso.md b/claude-memory/project-sso.md new file mode 100644 index 0000000..ec9fa6b --- /dev/null +++ b/claude-memory/project-sso.md @@ -0,0 +1,32 @@ +--- +name: project-sso +description: "Authentik SSO setup status for kitestacks.com — what's done vs pending" +metadata: + node_type: memory + type: project + originSessionId: 301d23e2-6920-42b0-a27d-eba4e667b7f7 +--- + +Authentik SSO configured 2026-06-08 to cover all kitestacks.com services. +Full reference: `docs/authentik-sso-setup.md` in the Forgejo repo. + +**Config files updated (done):** +- `apps/authentik/docker-compose.yml` — kitestacks network declared +- `apps/kavita/config/appsettings.json` — OIDC enabled, Authority set +- BookStack retired — not used, all books on Kavita +- `apps/openproject/docker-compose.yml` — OIDC env vars + network +- `apps/openproject/.env` — OPENPROJECT_OIDC_SECRET placeholder +- Grafana and OpenWebUI already had OIDC env vars (just need Authentik apps created) + +**Pending manual steps:** +1. Create Authentik OAuth2/OIDC providers + applications in admin UI for: Grafana, OpenWebUI, Kavita, OpenProject, Forgejo +2. Create Authentik Proxy Providers for: Shaarli, Uptime Kuma, LiteLLM; assign to Embedded Outpost +3. Configure Forgejo OAuth2 source via Forgejo admin UI (Site Admin → Auth Sources) +4. Fill client secrets in `.env` files and restart containers +5. Update Cloudflare tunnel routes: links.kitestacks.com → authentik:9000, status.kitestacks.com → authentik:9000, llm.kitestacks.com → authentik:9000 +6. After OpenProject container recreation (v13→v15 upgrade), update tunnel: tasks.kitestacks.com → openproject:80 + +**Excluded from SSO:** Portainer, Prometheus, Node Exporter, OpenRouter, BookStack (retired) + +**Why:** User requested Authentik SSO for all services; OpenRouter/Prometheus/node-exporter/Portainer excluded by user request. +**How to apply:** When user asks about SSO, check this memory for current status before suggesting next steps. diff --git a/claude-memory/user-profile.md b/claude-memory/user-profile.md new file mode 100644 index 0000000..ecc876c --- /dev/null +++ b/claude-memory/user-profile.md @@ -0,0 +1,10 @@ +--- +name: user-profile +description: "kenpat's role, preferences, and homelab context" +metadata: + node_type: memory + type: user + originSessionId: 301d23e2-6920-42b0-a27d-eba4e667b7f7 +--- + +kenpat runs a self-hosted homelab at kitestacks.com. All services exposed via Cloudflare Tunnels. Comfortable with Docker Compose, Git/Forgejo. Wants Claude to document changes and push them to Forgejo as part of completing any task.