Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 15 additions & 7 deletions src/content/docs/docs/getting-started/baremetal-ubuntu.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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`.

<Aside type="caution">
The old `amdgpu.gttsize` parameter is **deprecated** and may emit kernel
warnings on current amdgpu/TTM kernels — the GTT window is now driven
solely by `ttm.pages_limit`. Some newer kernels expose the same knob as
`amdttm.pages_limit` (the out-of-tree AMD TTM module) instead — check
which one your kernel ships with `modinfo ttm` / `modinfo amdttm` and set
whichever applies. Set only that knob; drop `amdgpu.gttsize` from any
older guide.
</Aside>

## 3. Install hal0

Expand Down
10 changes: 10 additions & 0 deletions src/content/docs/docs/getting-started/first-model.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<Aside type="tip" title="Where the pull lands">
Downloads write to `[models].store` in `hal0.toml` — the single directory
the pull engine writes to and slot containers bind-mount. It's empty by
default and falls back to the legacy `pull_root` (`/var/lib/hal0/models`)
until you set it explicitly with `hal0 setup --storage-dir <path>`
(first-run setup) or `hal0 model store <path>` (any time). See
[Paths and files](/docs/reference/paths-and-files/) for the full
resolution order.
</Aside>

## Via `hal0 setup`

If you ran [first-run setup](/docs/getting-started/setup/) and picked models
Expand Down
23 changes: 16 additions & 7 deletions src/content/docs/docs/getting-started/proxmox-lxc.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 |

<Aside type="tip">
`126976` MiB leaves only ~4 GB for the host on a 128 GB machine — fine for
a dedicated inference LXC, aggressive if the host runs other tenants.
Scale both numbers down together (they must stay equal) to reserve more
host RAM. After rebooting, `cat /proc/cmdline` should show the params.
`32505856` pages ≈ 124 GiB leaves only ~4 GB for the host on a 128 GB
machine — fine for a dedicated inference LXC, aggressive if the host runs
other tenants. Scale it down to reserve more host RAM. After rebooting,
`cat /proc/cmdline` should show the params.
</Aside>

<Aside type="caution">
The old `amdgpu.gttsize` parameter is **deprecated** and may emit kernel
warnings on current amdgpu/TTM kernels — the GTT window is now driven
solely by `ttm.pages_limit`. Some newer kernels expose the same knob as
`amdttm.pages_limit` (the out-of-tree AMD TTM module) instead — check
which one your kernel ships with `modinfo ttm` / `modinfo amdttm` and set
whichever applies. Set only that knob; drop `amdgpu.gttsize` from any
older guide.
</Aside>

## 2. Create the container
Expand Down
4 changes: 2 additions & 2 deletions src/content/docs/docs/guides/configure.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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".
Expand Down
19 changes: 1 addition & 18 deletions src/content/docs/docs/guides/enable-memory.mdx
Original file line number Diff line number Diff line change
@@ -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
---
Expand Down Expand Up @@ -131,23 +131,6 @@ unaffected either way — this gate only controls the graph layer.
</TabItem>
</Tabs>

## 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.

<Aside type="caution">
Migration is **dry-run only** today — it reports the plan without writing.
Passing `--no-dry-run` exits with a "not yet implemented" error.
</Aside>

## Destructive ops are audited

Every destructive call under `/api/memory/*` — bank delete, and the
Expand Down
8 changes: 8 additions & 0 deletions src/content/docs/docs/reference/api/rest-api.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 +
Expand Down
14 changes: 8 additions & 6 deletions src/content/docs/docs/reference/config-schema.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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). |

<Aside type="note">
The validator also accepts `cognee`/`mem0`, but the Advanced Settings dropdown
only offers `hindsight`/`pgvector` — the factory silently remaps `cognee`/`mem0`
selections to `hindsight`, so the dashboard doesn't offer a choice that would
lie about what actually runs. Hand-editing `hal0.toml` to `cognee`/`mem0` is
still accepted at the schema level, but resolves to `hindsight` in practice.
The validator accepts `mem0`, but the Advanced Settings dropdown only offers
`hindsight`/`pgvector` — the factory silently remaps `mem0` selections to
`hindsight`, so the dashboard doesn't offer a choice that would lie about
what actually runs. Hand-editing `hal0.toml` to `mem0` is still accepted at
the schema level, but resolves to `hindsight` in practice. `cognee` is no
longer a valid value at all — a `hal0.toml` still carrying it fails config
validation and must be updated to `hindsight`.
</Aside>

### `[memory.embedding]` — reranker knobs (Hindsight era)
Expand Down
6 changes: 6 additions & 0 deletions src/content/docs/docs/reference/mcp-tools.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down