From bbefaf41976e18e93cecad1498f905648bd1e180 Mon Sep 17 00:00:00 2001 From: Alexander Date: Mon, 27 Jul 2026 09:26:47 -0400 Subject: [PATCH] docs: port #1081 gttsize/ttm, #985 cognee retirement, #1083 pull destination MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Ports the hal0-side docs/v1-parity-sweep fix (Hal0ai/hal0, same branch name) forward into this repo's mirrored copies, so the next mirror-docs sync doesn't clobber it. Scoped to only the four target issues' own facts — does not sync unrelated drift between this branch's base (upstream/master@e1cef95) and hal0's current docs; see PR description / agent report for the divergence inventory. - #1081 (getting-started/baremetal-ubuntu.mdx, getting-started/proxmox-lxc.mdx): GTT sizing guidance drops amdgpu.gttsize from the GRUB example/table, uses ttm.pages_limit=32505856 as the sole knob, and adds a deprecation Aside covering the amdttm.pages_limit out-of-tree-TTM-module equivalent and the modinfo check to tell which applies. - #985 (guides/configure.mdx, guides/enable-memory.mdx, reference/config-schema.mdx): the 'cognee' memory-engine value is retired (schema now rejects it, docs updated to match); removed enable-memory.mdx's "Migrate a legacy store" section, which documented a `hal0 memory migrate --cognee-dir` flag that doesn't exist in the current CLI. - #1083 (getting-started/first-model.mdx): added a "Where the pull lands" note covering [models].store / the legacy pull_root fallback / --storage-dir, inserted standalone since this branch's first-model.mdx still describes the pre-#1082 bundle-picker first-run flow (see report for why #1084's fresh-box-state content was NOT ported here). Also ports two files from Hal0ai/hal0 branch fix/memory-delete-hardening (a different, concurrent lane) since they document a real, just-landed API behavior change and belong in the same coherent docs PR: - reference/api/rest-api.mdx: /api/memory is ADMIN-classed end-to-end; DESTRUCTIVE_MEMORY_ROUTES pins the irreversible subset above the generic prefix rule. - reference/mcp-tools.mdx: the memory_delete bulk-delete arity gate applies identically on both the /mcp/memory and /mcp/admin mounts. Verified: npx astro check — 5 pre-existing errors in src/content.config.ts (zod version mismatch between astro and starlight-blog) and src/pages/changelog.astro (implicit-any), confirmed present at this branch's HEAD before these changes too (stash-tested) — none touch the 8 files changed here. npm run build — 57 pages built clean, all 8 changed pages present in the output, 0 errors. Co-Authored-By: Claude Opus 5 (1M context) --- .../docs/getting-started/baremetal-ubuntu.mdx | 22 ++++++++++++------ .../docs/docs/getting-started/first-model.mdx | 10 ++++++++ .../docs/docs/getting-started/proxmox-lxc.mdx | 23 +++++++++++++------ src/content/docs/docs/guides/configure.mdx | 4 ++-- .../docs/docs/guides/enable-memory.mdx | 19 +-------------- .../docs/docs/reference/api/rest-api.mdx | 8 +++++++ .../docs/docs/reference/config-schema.mdx | 14 ++++++----- src/content/docs/docs/reference/mcp-tools.mdx | 6 +++++ 8 files changed, 66 insertions(+), 40 deletions(-) diff --git a/src/content/docs/docs/getting-started/baremetal-ubuntu.mdx b/src/content/docs/docs/getting-started/baremetal-ubuntu.mdx index a8a28d1..3eff723 100644 --- a/src/content/docs/docs/getting-started/baremetal-ubuntu.mdx +++ b/src/content/docs/docs/getting-started/baremetal-ubuntu.mdx @@ -51,19 +51,27 @@ on the host kernel command line: ```sh # /etc/default/grub — append to GRUB_CMDLINE_LINUX_DEFAULT -amd_iommu=off amdgpu.gttsize=126976 ttm.pages_limit=32505856 +amd_iommu=off ttm.pages_limit=32505856 ``` ```sh sudo update-grub && sudo reboot ``` -`amdgpu.gttsize` is in **MiB** (`126976` ≈ 124 GiB); `ttm.pages_limit` is -in **4 KiB pages** (`32505856` ≈ 124 GiB — keep it equal to `gttsize`); -`amd_iommu=off` is worth ~5–12% on this workload. These reference values -target a 128 GB box and leave only ~4 GB for the host — scale both down -together to reserve more host RAM. After rebooting, confirm with -`cat /proc/cmdline`. +`ttm.pages_limit` is the GTT cap in **4 KiB pages** (`32505856` ≈ 124 GiB); +`amd_iommu=off` is worth ~5–12% on this workload. This reference value +targets a 128 GB box and leaves only ~4 GB for the host — scale it down to +reserve more host RAM. After rebooting, confirm with `cat /proc/cmdline`. + + ## 3. Install hal0 diff --git a/src/content/docs/docs/getting-started/first-model.mdx b/src/content/docs/docs/getting-started/first-model.mdx index e084a4e..8bd9847 100644 --- a/src/content/docs/docs/getting-started/first-model.mdx +++ b/src/content/docs/docs/getting-started/first-model.mdx @@ -11,6 +11,16 @@ Models in hal0 live in a local registry, the single source of truth for Hugging Face coordinates, SHA-256 digests, and curated filenames. You can populate it through the `hal0 setup` TUI or directly from the CLI. + + ## Via `hal0 setup` If you ran [first-run setup](/docs/getting-started/setup/) and picked models diff --git a/src/content/docs/docs/getting-started/proxmox-lxc.mdx b/src/content/docs/docs/getting-started/proxmox-lxc.mdx index a9c032c..9897da5 100644 --- a/src/content/docs/docs/getting-started/proxmox-lxc.mdx +++ b/src/content/docs/docs/getting-started/proxmox-lxc.mdx @@ -58,20 +58,29 @@ hal0's profile-tuning work are: ```sh # /etc/default/grub — append to GRUB_CMDLINE_LINUX_DEFAULT, then update-grub && reboot -amd_iommu=off amdgpu.gttsize=126976 ttm.pages_limit=32505856 +amd_iommu=off ttm.pages_limit=32505856 ``` | Parameter | Value | Meaning | |---|---|---| -| `amdgpu.gttsize` | `126976` | GTT window in **MiB** (≈ 124 GiB) | -| `ttm.pages_limit` | `32505856` | TTM page cap in **4 KiB pages** (≈ 124 GiB — keep it equal to `gttsize`) | +| `ttm.pages_limit` | `32505856` | GTT cap in **4 KiB pages** (≈ 124 GiB) | | `amd_iommu=off` | — | Disables the IOMMU; measured worth ~5–12% on this workload | + + ## 2. Create the container diff --git a/src/content/docs/docs/guides/configure.mdx b/src/content/docs/docs/guides/configure.mdx index 1f7886d..600570b 100644 --- a/src/content/docs/docs/guides/configure.mdx +++ b/src/content/docs/docs/guides/configure.mdx @@ -120,8 +120,8 @@ Advanced, About. `[memory]`, and `[activity]` key that previously required `hal0 config edit` (including `slots.evict_pressure_mb`, the pressure-eviction floor; the `memory.engine` picker only offers `hindsight`/`pgvector` even though - the schema also accepts `cognee`/`mem0`, since those two are silently - remapped to hindsight), plus a dedicated **memory graph** panel for + the schema also accepts `mem0`, since it's silently remapped to + hindsight), plus a dedicated **memory graph** panel for `[memory.graph]` (`extraction_slot`, `llm_timeout_s`) and a **Restart hal0-api** button — a one-click restart-and-health-poll for `hal0-api.service`, handy after any change flagged "restart required". diff --git a/src/content/docs/docs/guides/enable-memory.mdx b/src/content/docs/docs/guides/enable-memory.mdx index 6901d59..2453bb5 100644 --- a/src/content/docs/docs/guides/enable-memory.mdx +++ b/src/content/docs/docs/guides/enable-memory.mdx @@ -1,6 +1,6 @@ --- title: Enable memory -description: hal0's memory subsystem is gated by HAL0_MEMORY_ENABLED (on by default on a fresh install). Control graph extraction with hal0 memory graph --slot, and migrate any legacy store. +description: hal0's memory subsystem is gated by HAL0_MEMORY_ENABLED (on by default on a fresh install). Control graph extraction with hal0 memory graph --slot. sidebar: order: 50 --- @@ -131,23 +131,6 @@ unaffected either way — this gate only controls the graph layer. -## Migrate a legacy store - -If you previously ran the Cognee-backed memory store, preview a migration -into Hindsight banks: - -```sh -hal0 memory migrate --dry-run -hal0 memory migrate --dry-run --cognee-dir /var/lib/hal0/memory/cognee -``` - -The report shows rows total / mapped / unmapped and whether it's a no-op. - - - ## Destructive ops are audited Every destructive call under `/api/memory/*` — bank delete, and the diff --git a/src/content/docs/docs/reference/api/rest-api.mdx b/src/content/docs/docs/reference/api/rest-api.mdx index 59b92b6..6a18ab8 100644 --- a/src/content/docs/docs/reference/api/rest-api.mdx +++ b/src/content/docs/docs/reference/api/rest-api.mdx @@ -89,6 +89,14 @@ See [Services](/docs/operate/services) for the operator-facing guide (registry, ### `/api/memory` — hardening +- The whole `/api/memory` surface — reads included — is **ADMIN**-classed in + the route exposure table, so once auth is enabled every call needs an admin + credential (session cookie or admin bearer); a client/inference key gets + `403`. The irreversible subset (every `DELETE` under `/api/memory`, plus the + namespace `POST /api/memory/delete`) is additionally pinned by name in + `DESTRUCTIVE_MEMORY_ROUTES` and matched by rules that sit *above* the generic + prefix rule, so a later decision to open memory reads cannot take the bank + wipe with it. - Every destructive `/api/memory/*` operation — bank delete, and the memories/config/document/directive/operation/mental-model deletes, plus the namespace `POST /api/memory/delete` — records a durable audit row (actor + diff --git a/src/content/docs/docs/reference/config-schema.mdx b/src/content/docs/docs/reference/config-schema.mdx index a6a14ab..7d18270 100644 --- a/src/content/docs/docs/reference/config-schema.mdx +++ b/src/content/docs/docs/reference/config-schema.mdx @@ -113,14 +113,16 @@ fast disk / network mount to align pulls and slot bind-mounts on one path. | Key | Type | Default | Notes | |---|---|---|---| -| `engine` | str | `"hindsight"` | Active memory engine: `cognee` \| `hindsight` \| `mem0` \| `pgvector`. `hindsight` is the current default. | +| `engine` | str | `"hindsight"` | Active memory engine: `hindsight` (default) \| `mem0` \| `pgvector`. `cognee` was **retired in v1.0.0** — the schema now rejects it (the Cognee store has been dark since v0.4). | ### `[memory.embedding]` — reranker knobs (Hindsight era) diff --git a/src/content/docs/docs/reference/mcp-tools.mdx b/src/content/docs/docs/reference/mcp-tools.mdx index 3797f3c..4ab500c 100644 --- a/src/content/docs/docs/reference/mcp-tools.mdx +++ b/src/content/docs/docs/reference/mcp-tools.mdx @@ -42,6 +42,12 @@ calls degrade to a no-op / unavailable surface. | `memory_list` | autonomous-read | Paginated walk → `{items, next_cursor}`. | | `memory_delete` | conditional | Remove by id(s) → `{deleted}`. **Autonomous** for one id; **gated** for >1. | +The `memory_delete` arity gate applies on **both** mounts — `/mcp/memory` and +`/mcp/admin` evaluate the same rule and enqueue on the same approval queue, so +a bulk delete lands in one operator inbox no matter which server the agent is +connected to. A `/mcp/memory` server built without an approval queue refuses +bulk deletes outright rather than running them ungated. + Notable arguments: - `dataset` defaults to `shared`; private-mode callers promote to