# GLAMMBRAIN — install guide for your AI agent You are an AI coding agent (Claude Code, Codex, or similar) with a shell on the owner's machine. The owner wants GLAMMBRAIN: a local memory for their own AI (a meaning index, an exact-word index, an optional relationship graph, local models, and scheduled jobs that turn activity into readable memory files). Follow this page in order. Report what you actually observe, never plausible output. - Package: `https://glammbox-v1.vercel.app/downloads/glammbrain-20260827-full-v4.tar.gz` - Size: 5,417,952 bytes - SHA-256: `c7fde89a22ba289891041c25718891921312f107d0b1a9e7184f6147299c2723` - Inside the archive, `brain-engine/AGENT-PACK.md` is the authoritative work order. This page is the map; where the two differ, AGENT-PACK.md wins. - The brain ships **EMPTY**. Model weights are **not** bundled: installation downloads about 12 GB of models and caches, plus Python packages and container images. 20 GB free disk is the recommended floor. - Supported: Linux with systemd, or WSL2 with systemd and Docker integration. macOS: guided beta (no systemd; services and timers need a scheduler the owner chooses). Native Windows without WSL: experimental. A container or sandbox without a systemd user manager and a Docker daemon cannot host GLAMMBRAIN. ## Ask the owner before - installing Docker, Ollama, Python or any other system package, changing host virtualization, or freeing disk space; - feeding any content (`feed.py --force`) — only after the owner names the exact folder; - anything destructive in the uninstall section (`down -v`, deleting caches or the workspace); - skipping the graph (`--without-graph`) or the timers (`--no-timers`), unless the owner asked for it. This is the only list of owner questions. Everything else on this page you run yourself, in order. ## 1. Check the machine (read-only, before anything is downloaded) ```bash for c in docker ollama tar flock sha256sum curl; do command -v "$c" >/dev/null 2>&1 && echo "$c: OK" || echo "$c: MISSING"; done docker compose version >/dev/null 2>&1 && echo "docker compose: OK" || echo "docker compose: MISSING" ollama list >/dev/null 2>&1 && echo "ollama server: OK" || echo "ollama server: NOT REACHABLE" python3 -c 'import sys; print("python", sys.version.split()[0], "OK" if sys.version_info >= (3, 12) else "TOO OLD: need 3.12+")' systemctl --user show-environment >/dev/null 2>&1 && echo "systemd user manager: OK" || echo "systemd user manager: MISSING" df -h "$HOME" ``` Continue only if every line says `OK` (a missing `curl` is fine) and `df` shows 20 GB free. If any is missing, stop here: report each missing item with the exact command and output, and ask the owner (installing or starting any of them is on the list above). ## 2. Download, check, extract ```bash curl -fL -o glammbrain-20260827-full-v4.tar.gz \ https://glammbox-v1.vercel.app/downloads/glammbrain-20260827-full-v4.tar.gz ``` Without `curl`, the same download with Python: ```bash python3 -c 'import urllib.request as u; u.urlretrieve("https://glammbox-v1.vercel.app/downloads/glammbrain-20260827-full-v4.tar.gz", "glammbrain-20260827-full-v4.tar.gz")' ``` Then check and extract: ```bash echo "c7fde89a22ba289891041c25718891921312f107d0b1a9e7184f6147299c2723 glammbrain-20260827-full-v4.tar.gz" | sha256sum -c - tar xzf glammbrain-20260827-full-v4.tar.gz cd cockpit-20260827 ``` Stop if the checksum line does not end in `OK`. All paths below are relative to `cockpit-20260827/`. ## The seven layers, in install order `brain-engine/infra/install-brain.sh` builds layers 2–7 in one run (the step numbers below are the ones it prints; its flags are in `brain-engine/INSTALL.md`, "Run the installer"). Layer 1 is what step 1 above checked; layers 2–7 are what the installer creates, and what the verifier and dry runs prove afterwards. | # | Layer | What it is | Installer step(s) | |---|---|---|---| | 1 | Prerequisites | Docker + `docker compose`, Python 3.12+ with venv, Ollama (server reachable), `tar`, `flock`, a systemd user manager, 20 GB free; optional NVIDIA GPU (~2.4 GB free VRAM) for the primary reranker | 1 (checks) | | 2 | Local configuration | `brain-engine/infra/.env` with generated Qdrant/Neo4j secrets (mode 0600); an empty `brain-workspace/`; loopback endpoints written to `server/owner.config.json` | 2 | | 3 | Stores | Qdrant `v1.17.1` on loopback 6333/6334 with three empty 768-d cosine collections (`knowledge`, `memory`, `code`); Neo4j 5 Community on loopback 7474/7687 (the optional relationship graph) | 3, 6 | | 4 | Python environment | `brain-engine/infra/.venv` with the pinned `brain-engine/requirements.txt` | 5 | | 5 | Models | Ollama: `embeddinggemma:300m`, `qwen3-embedding:0.6b`, `gemma4:12b`; Hugging Face rerankers `BAAI/bge-reranker-v2-m3` (GPU) and `cross-encoder/ms-marco-MiniLM-L-6-v2` (CPU), via `brain-engine/models/pull-models.sh` | 4, 5b | | 6 | Search services | an empty BM25 exact-word index, the BM25 service (loopback 18794) and the reranker service (loopback 18793) as systemd **user** units `glammbrain-bm25.service`, `glammbrain-reranker.service` | 7, 8 | | 7 | Upper layers and schedule | the memory jobs in `brain-engine/layers/` and four user timers: nightly ingest 03:20, hot ingest every hour at :50, dream 04:20, deep dream Sunday 05:00; then a synthetic feed/search smoke test that cleans up after itself | 8, 9 | ## 3. Syntax check before anything changes (read-only) ```bash bash -n brain-engine/infra/install-brain.sh bash -n brain-engine/infra/verify-brain.sh bash -n brain-engine/models/pull-models.sh bash -n brain-engine/layers/hot-ingest.sh PYTHONPYCACHEPREFIX=/tmp/glammbrain-pycache \ python3 -m py_compile brain-engine/brain/brain_config.py brain-engine/layers/*.py ``` Any nonzero exit blocks installation; report the file and the error. ## 4. Install layers 2–7 ```bash (cd brain-engine/infra && bash install-brain.sh) # flags: --no-timers --without-graph --skip-smoke-test --help ``` The installer re-checks layer 1 and exits with `missing required prerequisites` before it changes anything if one is absent. The first install is long (model downloads). Do not interrupt a quiet but healthy download. Any `FAIL` line in the installer's final receipt means the install is incomplete, even if the script reached its end. **Side-by-side or throwaway install** next to an existing one: write the isolation settings into `brain-engine/infra/.env` BEFORE the first run, so the installer, the verifier and the uninstall all read the same names and ports: ```bash cp brain-engine/infra/.env.example brain-engine/infra/.env chmod 600 brain-engine/infra/.env sed -i \ -e 's/^BRAIN_COMPOSE_PROJECT_NAME=.*/BRAIN_COMPOSE_PROJECT_NAME=glammbrain-test/' \ -e 's/^BRAIN_SYSTEMD_SERVICE_PREFIX=.*/BRAIN_SYSTEMD_SERVICE_PREFIX=glammbrain-test/' \ -e 's/^BRAIN_QDRANT_HTTP_PORT=.*/BRAIN_QDRANT_HTTP_PORT=16333/' \ -e 's/^BRAIN_QDRANT_GRPC_PORT=.*/BRAIN_QDRANT_GRPC_PORT=16334/' \ -e 's/^BRAIN_NEO4J_HTTP_PORT=.*/BRAIN_NEO4J_HTTP_PORT=17474/' \ -e 's/^BRAIN_NEO4J_BOLT_PORT=.*/BRAIN_NEO4J_BOLT_PORT=17687/' \ -e 's/^BRAIN_BM25_PORT=.*/BRAIN_BM25_PORT=28794/' \ -e 's/^BRAIN_RERANKER_PORT=.*/BRAIN_RERANKER_PORT=28793/' \ brain-engine/infra/.env (cd brain-engine/infra && bash install-brain.sh --no-timers) ``` ## 5. Verify layers 2–7 ```bash PREFIX="$(grep -E '^BRAIN_SYSTEMD_SERVICE_PREFIX=' brain-engine/infra/.env | cut -d= -f2)" bash brain-engine/infra/verify-brain.sh systemctl --user list-timers --all "${PREFIX:-glammbrain}-*" ollama list ``` On a fresh install, scheduled layers may report `PENDING` and input-driven ones `ON_DEMAND`. Report those words exactly; never rewrite them as `PASS`. Then prove every upper layer has a non-mutating path: run the dry-run list in `brain-engine/AGENT-PACK.md` section 7 (it sets `PY=brain-engine/infra/.venv/bin/python3`). Every command must exit 0 and none may write a layer receipt. Finally confirm the empty-brain contract (AGENT-PACK.md section 8): no owner folder selected or fed, zero-point collections are normal. ## 6. Return the receipt Use the receipt template in `brain-engine/AGENT-PACK.md` section 9, filled with observed values only. Report `PASS` only when the infrastructure, model downloads, smoke test, verifier, timers (unless skipped by the owner) and every dry run are green. If you stopped at step 1, return that template with `FAIL`, the observed platform, and every missing prerequisite under "Blockers/failures". ## Uninstall Stops the services, the timers and the containers of THIS install (names read from its `.env`); keeps Docker volumes and model caches: ```bash ENV=brain-engine/infra/.env PROJECT="$(grep -E '^BRAIN_COMPOSE_PROJECT_NAME=' "$ENV" | cut -d= -f2)"; PROJECT="${PROJECT:-glammbrain}" PREFIX="$(grep -E '^BRAIN_SYSTEMD_SERVICE_PREFIX=' "$ENV" | cut -d= -f2)"; PREFIX="${PREFIX:-glammbrain}" systemctl --user disable --now \ "$PREFIX-nightly-ingest.timer" "$PREFIX-hot-ingest.timer" \ "$PREFIX-dream.timer" "$PREFIX-deep-dream.timer" \ "$PREFIX-bm25.service" "$PREFIX-reranker.service" docker compose -p "$PROJECT" -f brain-engine/infra/docker-compose.yml \ --env-file "$ENV" --profile graph down ``` The `-p` matters: the installer names the Compose project from `BRAIN_COMPOSE_PROJECT_NAME`, and without it `down` looks for a project called `infra` and stops nothing. Adding `-v`, deleting `brain-engine/infra/.venv`, deleting the Ollama or Hugging Face caches, or removing the workspace destroys data: ask the owner first. The cockpit app (optional, `install/install.sh`) has its own `install/uninstall.sh`. ## Truth boundaries - The package ships empty; no one's memory, documents, sessions or model weights are inside. - Real setup still involves downloads, disk space, credentials and possible service failures. - Everything binds to loopback by default; that is not a guarantee about the host, its network, or later changes. - Model downloads contact Ollama and Hugging Face at install time.