From 7893037d688edaca39dcc92af1ec8fb92415aeb3 Mon Sep 17 00:00:00 2001 From: Alexander Date: Mon, 27 Jul 2026 09:13:36 -0400 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20v1.0=20parity=20sweep=20=E2=80=94?= =?UTF-8?q?=20gttsize/ttm,=20cognee=20retirement,=20fresh-box=20journey?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes the remaining gaps on #1081, #1084, #1083, and #985 left over from the earlier ba72db29 sweep: - #1081: baremetal-ubuntu.mdx / proxmox-lxc.mdx now mention amdttm.pages_limit as the out-of-tree-TTM-module equivalent of ttm.pages_limit, with the modinfo check to tell which applies; memory-map.jsx's stale amdgpu.gttsize code comment now says ttm.pages_limit. - #1083: first-model.mdx documents the pull destination ([models].store, falling back to the deprecated pull_root, set via hal0 setup --storage-dir or hal0 model store). - #1084: first-model.mdx's "Starting from zero" section now covers the OpenWebUI empty model selector and corrects the hal0 status/hal0 slot list claim — the installer scaffolds slot structure (no --no-slots in install.sh), so slots show up with no model assigned rather than an empty list. Verified the installer "Next steps" block and the dashboard FirstRunBanner copy already point at hal0 setup / hal0 model pull correctly; no in-product changes were needed. - #985: retired the 'cognee' memory-engine enum value (schema.py) now that v1.0.0 is the scheduled HAL0-SUNSET removal point — the validator rejects it instead of silently resolving it to hindsight; updated the matching test and the config-schema.mdx / configure.mdx docs. Stripped the last two dangling non-ADR-0023 comment citations (ADR-0004 in agents/manager.py, ADR-0012 in provider_hal0/profile.py) preserving their inline rationale. Removed enable-memory.mdx's "Migrate a legacy store" section, which documented a hal0 memory migrate --cognee-dir flag that no longer exists in the CLI (migrate now only does Honcho<->Hindsight); pointed readers at the real command in honcho-memory.mdx instead. Verified: ruff check/format clean; tests/config + tests/memory + tests/agents/test_manager.py all pass (854 passed, 9 skipped); internal /docs/ links in every changed file resolve to an existing page. Co-Authored-By: Claude Opus 5 (1M context) --- docs/getting-started/baremetal-ubuntu.mdx | 10 ++++++--- docs/getting-started/first-model.mdx | 21 ++++++++++++++++-- docs/getting-started/proxmox-lxc.mdx | 10 ++++++--- docs/guides/configure.mdx | 4 ++-- docs/guides/enable-memory.mdx | 22 ++++--------------- docs/reference/config-schema.mdx | 14 +++++++----- .../hermes/plugins/provider_hal0/profile.py | 5 +++-- src/hal0/agents/manager.py | 6 ++--- src/hal0/config/schema.py | 22 ++++++++++++------- tests/config/test_memory_engine_field.py | 10 ++++++++- ui/src/dash/memory-map.jsx | 2 +- 11 files changed, 77 insertions(+), 49 deletions(-) diff --git a/docs/getting-started/baremetal-ubuntu.mdx b/docs/getting-started/baremetal-ubuntu.mdx index 65a9a6eb7..3234ec41a 100644 --- a/docs/getting-started/baremetal-ubuntu.mdx +++ b/docs/getting-started/baremetal-ubuntu.mdx @@ -64,9 +64,13 @@ 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/docs/getting-started/first-model.mdx b/docs/getting-started/first-model.mdx index 065915847..b70f48064 100644 --- a/docs/getting-started/first-model.mdx +++ b/docs/getting-started/first-model.mdx @@ -25,8 +25,14 @@ shows up in a few places: - The **Models** view has an empty registry (the Inference tab reads "the catalog is empty"), and the Downloads panel prompts you to add a model from the catalog or via **Add by HF coords**. -- The **Slots** view shows a **no slots configured** hint if no capability - slots exist yet. +- **OpenWebUI** (`:3001`) is reachable, but its model selector is empty — it + reads the same empty `/v1/models` list below. +- The **Slots** view, `hal0 status`, and `hal0 slot list` show the + capability slots the installer scaffolded (structure only — device, + profile, port) with no model assigned, rather than an empty list: the + installer creates slot *shape*, never model picks. The one case where + these are truly empty is an install that skipped slot scaffolding + entirely with `hal0 setup --no-slots`. - `GET /v1/models` returns an empty list, and a chat request against an unconfigured slot has nothing to dispatch to. @@ -51,6 +57,17 @@ hal0 model run qwen3-4b # assign to a slot, load, wait until serving polls until the server answers, and prints a copy-paste `curl` smoke test against the slot port. That's a working chat endpoint. + + ## Already have the files on disk? Many installs start from a disk full of GGUFs, not a download. Point hal0 diff --git a/docs/getting-started/proxmox-lxc.mdx b/docs/getting-started/proxmox-lxc.mdx index 86e2b8ee2..71284d2ee 100644 --- a/docs/getting-started/proxmox-lxc.mdx +++ b/docs/getting-started/proxmox-lxc.mdx @@ -96,9 +96,13 @@ other tenants. Scale it down to reserve more host RAM. After rebooting, ## 2. Create the container diff --git a/docs/guides/configure.mdx b/docs/guides/configure.mdx index 1a4ed04bf..d28377e16 100644 --- a/docs/guides/configure.mdx +++ b/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/docs/guides/enable-memory.mdx b/docs/guides/enable-memory.mdx index 0758f5b42..f29fe4dff 100644 --- a/docs/guides/enable-memory.mdx +++ b/docs/guides/enable-memory.mdx @@ -1,6 +1,6 @@ --- title: Enable memory -description: hal0's memory subsystem is gated by [memory].enabled in hal0.toml (on by default). Toggle it with hal0 memory enable/disable, control graph extraction with hal0 memory graph --slot, and migrate any legacy store. +description: hal0's memory subsystem is gated by [memory].enabled in hal0.toml (on by default). Toggle it with hal0 memory enable/disable and control graph extraction with hal0 memory graph --slot. sidebar: order: 50 --- @@ -132,23 +132,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 @@ -167,3 +150,6 @@ confirmation is rejected with `memory.confirm_required`. the memory store. - [MCP tools](/docs/reference/mcp-tools) — the `memory_*` tool tiers and the `/mcp/memory` server this guide's flag gates. +- [Honcho memory](/docs/guides/honcho-memory) — `hal0 memory migrate --from + --to ` moves an agent's memories between Hindsight and + Honcho. diff --git a/docs/reference/config-schema.mdx b/docs/reference/config-schema.mdx index 46ed5722a..221402716 100644 --- a/docs/reference/config-schema.mdx +++ b/docs/reference/config-schema.mdx @@ -116,14 +116,16 @@ NPU weights off the root filesystem too. | Key | Type | Default | Notes | |---|---|---|---| -| `engine` | str | `"hindsight"` | Active memory engine: `hindsight` (default) \| `mem0` \| `pgvector`. `cognee` is **deprecated** — accepted for back-compat but resolves to `hindsight`. | +| `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/hal0/agents/hermes/plugins/provider_hal0/profile.py b/src/hal0/agents/hermes/plugins/provider_hal0/profile.py index 633ba7404..31402c14d 100644 --- a/src/hal0/agents/hermes/plugins/provider_hal0/profile.py +++ b/src/hal0/agents/hermes/plugins/provider_hal0/profile.py @@ -8,8 +8,9 @@ purely *declarative*: it advertises the endpoint, capabilities, and a live model inventory; it does not itself stream tokens. * ``base_url = "http://127.0.0.1:8080/v1"`` — loopback hal0-api (never a slot - port). No Bearer on the hal0 LAN (post-ADR-0012 identity model); identity is - carried by ``X-hal0-Agent`` when we make our own discovery call. + port). No Bearer on the hal0 LAN — hal0 ships with no built-in auth on the + trusted local network; identity is carried by ``X-hal0-Agent`` when we make + our own discovery call. * ``default_aux_model = "hal0/agent"`` — pins compression / vision / summarization / web_extract aux calls at the local agent slot. ``hal0/agent`` is a *virtual* name hal0 resolves per-request via its LiveSlotResolver, so diff --git a/src/hal0/agents/manager.py b/src/hal0/agents/manager.py index c1a0870b7..710c00821 100644 --- a/src/hal0/agents/manager.py +++ b/src/hal0/agents/manager.py @@ -315,9 +315,9 @@ def install( # Already installed — return the existing record. Idempotent. return self._read_record(name) - # Single-pick (ADR-0004 §2): only one bundled agent may be installed - # at a time. ``blocking`` == ``current`` — anything already - # installed conflicts with a fresh install. + # Single-pick: only one bundled agent may be installed at a time. + # ``blocking`` == ``current`` — anything already installed conflicts + # with a fresh install. blocking = current if not blocking: diff --git a/src/hal0/config/schema.py b/src/hal0/config/schema.py index 36225f39a..b7989751a 100644 --- a/src/hal0/config/schema.py +++ b/src/hal0/config/schema.py @@ -2440,16 +2440,22 @@ class MemoryConfig(BaseModel): "(private: / project: banks + fan-out recall)." ), ) - # HAL0-SUNSET: v1.0.0 — 'cognee' engine value resolves to hindsight at runtime; drop the alias. + # HAL0-SUNSET: v1.0.0 — 'cognee' engine literal retired here. It is no + # longer an accepted config value (was previously a back-compat alias + # that resolved to hindsight at runtime). provider_from_config's runtime + # resolution still treats any *unrecognized* engine as Hindsight as a + # defense-in-depth fallback for callers that bypass this validator + # (e.g. duck-typed namespaces), but a hal0.toml with engine = "cognee" + # now fails config validation outright — the Cognee store has been dark + # since v0.4. engine: str = Field( default="hindsight", description=( "Active memory engine. 'hindsight' (default) is the platform " - "engine; 'mem0' and 'pgvector' are alternates. 'cognee' is " - "DEPRECATED — the legacy Cognee store has been dark since v0.4 and " - "its wrapper was removed; the value is still accepted for " - "back-compat but resolves to 'hindsight' at runtime. Use " - "'hindsight'." + "engine; 'mem0' and 'pgvector' are alternates. The legacy " + "'cognee' value was retired in v1.0.0 (the Cognee store has been " + "dark since v0.4 and its wrapper was removed) — a hal0.toml " + "still carrying it must be updated to 'hindsight'." ), ) agent_providers: dict[str, str] = Field( @@ -2476,8 +2482,8 @@ class MemoryConfig(BaseModel): @field_validator("engine") @classmethod def _engine_is_known(cls, v: str) -> str: - known = {"cognee", "hindsight", "mem0", "pgvector"} - s = str(v or "cognee").strip().lower() + known = {"hindsight", "mem0", "pgvector"} + s = str(v or "hindsight").strip().lower() if s not in known: raise ValueError(f"memory.engine {v!r} must be one of {sorted(known)}") return s diff --git a/tests/config/test_memory_engine_field.py b/tests/config/test_memory_engine_field.py index 1d8a11a2f..4e0d33c8b 100644 --- a/tests/config/test_memory_engine_field.py +++ b/tests/config/test_memory_engine_field.py @@ -13,10 +13,18 @@ def test_engine_defaults_to_hindsight(): def test_engine_accepts_known_engines(): - for e in ("cognee", "hindsight", "mem0", "pgvector"): + for e in ("hindsight", "mem0", "pgvector"): assert MemoryConfig(engine=e).engine == e def test_engine_rejects_unknown(): with pytest.raises(ValidationError): MemoryConfig(engine="weaviate") + + +def test_engine_rejects_retired_cognee_literal(): + # HAL0-SUNSET: v1.0.0 — 'cognee' was a back-compat alias that resolved to + # hindsight at runtime; it is now retired and fails validation like any + # other unknown engine. The Cognee store has been dark since v0.4. + with pytest.raises(ValidationError): + MemoryConfig(engine="cognee") diff --git a/ui/src/dash/memory-map.jsx b/ui/src/dash/memory-map.jsx index a6d1c52a2..b09db051b 100644 --- a/ui/src/dash/memory-map.jsx +++ b/ui/src/dash/memory-map.jsx @@ -121,7 +121,7 @@ export function useMemoryMapModel() { const slots = slotsQ.data || [] // Pool total = the real ceiling for GPU model loads. On UMA (Strix Halo) - // that is the GTT cap (amdgpu.gttsize, ~80 GiB — live as + // that is the GTT cap (ttm.pages_limit, ~80 GiB — live as // stats.gpu_vram_total_mb), NOT the full unified RAM (128 GiB): models can't // actually allocate past the GTT window, so headroom must be measured // against it. Prefer the live GTT cap; fall back to the static unified/ram From b32a8fc14f5d476d971347f363ff5b1fa1a63fcf Mon Sep 17 00:00:00 2001 From: Alexander Date: Mon, 27 Jul 2026 10:54:37 -0400 Subject: [PATCH 2/2] fix(installer): sync the hal0-provider seed profile with canonical source The ADR-citation cleanup edited src/hal0/agents/hermes/plugins/provider_hal0/ profile.py; installer/agents/hermes/plugins/hal0-provider/profile.py is a byte-identical seed copy pinned by a drift test. Co-Authored-By: Claude Opus 5 (1M context) --- installer/agents/hermes/plugins/hal0-provider/profile.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/installer/agents/hermes/plugins/hal0-provider/profile.py b/installer/agents/hermes/plugins/hal0-provider/profile.py index 633ba7404..31402c14d 100644 --- a/installer/agents/hermes/plugins/hal0-provider/profile.py +++ b/installer/agents/hermes/plugins/hal0-provider/profile.py @@ -8,8 +8,9 @@ purely *declarative*: it advertises the endpoint, capabilities, and a live model inventory; it does not itself stream tokens. * ``base_url = "http://127.0.0.1:8080/v1"`` — loopback hal0-api (never a slot - port). No Bearer on the hal0 LAN (post-ADR-0012 identity model); identity is - carried by ``X-hal0-Agent`` when we make our own discovery call. + port). No Bearer on the hal0 LAN — hal0 ships with no built-in auth on the + trusted local network; identity is carried by ``X-hal0-Agent`` when we make + our own discovery call. * ``default_aux_model = "hal0/agent"`` — pins compression / vision / summarization / web_extract aux calls at the local agent slot. ``hal0/agent`` is a *virtual* name hal0 resolves per-request via its LiveSlotResolver, so