seth-linux-theme/SESSION.md

MAIN OBJECTIVE: Create SESSION.md in your project directory according to the folliwing template. Do NOT modify this source file.

SESSION.md — Persistent AI Session Memory

This is the template and guide for SESSION.md files used across projects in this homelab.

---

What SESSION.md is for

SESSION.md is a persistent memory file — it accumulates decisions, discoveries, and context across AI coding sessions so the assistant doesn't start cold each time.

It is not a chat transcript.
It is not static documentation of how something works.
It is a living record of why things are the way they are, plus a map to the right context files.

---

Where to put it

Scope	Location	Purpose
Global homelab	/root/bin/SESSION.md ← this file	Cross-project memory, patterns, major decisions
Per-project	<project-dir>/SESSION.md	Project-specific session memory

Each project SESSION.md should link back here and to any relevant context files.

---

How to populate it

Copy the section structure below into your project's SESSION.md and fill it in.

Mandatory sections

Context pointers — every SESSION.md must list the files the AI should load to understand the project:

## Context Files

- `/root/bin/core_homelab.md` — cluster topology, SSH aliases
- `/root/bin/services_directory.md` — active service IPs and domains
- `/root/bin/SESSION.md` — global session memory (this file's parent)
- `./CONTEXT.md` — project-specific infrastructure and config
- `./README.md` — project overview

Project summary — one paragraph. What is this project? What problem does it solve?

Gitea repo — link to the Gitea remote (if version-controlled):

## Gitea

- Repo: https://git.sethpc.xyz/Seth/<repo-name>
- Remote: `https://Seth:<token>@git.sethpc.xyz/Seth/<repo-name>.git`
- API key: see `/root/bin/GITEA_API.md` (same key for all repos)

Session notes — the meat of the file. Append here each session.

---

Session notes format

Group entries by topic, not by date. Update the relevant section rather than appending raw timestamped blocks. Example:

## Session Notes

### Infrastructure decisions
- Chose LXC over Docker-in-LXC because the service doesn't need container isolation
- Enabled nesting=1 on CT 644 to allow Docker inside

### Bug fixes & discoveries
- Service wasn't starting: mc1 had autoStart=false in MCSManager config
  (fixed: set eventTask.autoStart=true in InstanceConfig/<id>.json)
- tail -F (capital F) is correct — waits for file to appear, handles log rotation

### Open threads
- [ ] Add Redis backend for session persistence (currently SQLite only)
- [ ] Web dashboard for recent AI god interactions

---

How to keep it current

Run /update-context in OpenCode at the end of any session. The command will:

1. Scan the conversation for decisions, fixes, and discoveries not yet recorded
2. Append them to SESSION.md (both this file and the project-level one if applicable)
3. Commit and push to Gitea

Command defined at: ~/.config/opencode/commands/update-context.md

Mandatory per-reply discipline:

• Update SESSION.md immediately when a durable fact, decision, or fix is discovered.
• Before every final reply, run a memory check and append any missing durable notes.
• End every reply with one line: Session memory: updated or Session memory: no new durable facts.

---

Global session notes

Patterns established across all projects

• Gitea backup convention: commit every meaningful change immediately; push on the same command. No squashing, no batching unrelated changes.
• Session file naming: SESSION.md (not CONVERSATION.md, not CONTEXT.md). CONTEXT.md = static infra facts. SESSION.md = accumulated AI memory.
• Context file loading: Always include core_homelab.md and services_directory.md in project instructions. Specific project context goes in CONTEXT.md.
• autoStart for MCSManager instances: Must be set in InstanceConfig/<id>.json (eventTask.autoStart: true), not just in the panel UI, to survive daemon restarts.

Infrastructure discoveries

• mc-godmode.service on CT 644: already enabled and using tail -F correctly. The MC server itself had autoStart: false — that was the real issue.
• Gitea runs on port 443 via Caddy at git.sethpc.xyz (CT 146, node-173). Direct access to 192.168.0.125:80 does not work from CT 629 — always use the domain.