Enable memory

hal0’s memory subsystem is gated by a single environment flag, HAL0_MEMORY_ENABLED. When it’s on, hal0 gives agents a persistent recall store — Hindsight — plus an optional knowledge-graph extraction layer. Flipping the flag is a single environment change — no code change, no reinstall.

Note

A fresh install turns this on for you: the one-line installer writes HAL0_MEMORY_ENABLED=1 into /etc/hal0/api.env and stands up the local Hindsight daemon automatically (skip it at install time with HAL0_SKIP_HINDSIGHT=1). The steps below are for the cases the installer doesn’t cover: a box that predates the default flip, a manual/source install, or re-enabling memory after you turned it off. In every case, every downstream caller — the admin MCP tools, the /api/memory/* routes, the agent memory provider — degrades to a no-op or 503 when memory is off, so flipping the flag is the whole toggle either way.

Hermes ships with its own durable-memory wiring already pointed at this subsystem (memory.provider=hal0-memory, two banks — private:hermes and shared) — see What memory powers for how that fits together. Hermes’s memory calls still need HAL0_MEMORY_ENABLED=1 on the hal0-api side to actually work; without it they degrade the same as every other caller.

Turn it on

1. Set the flag. Add HAL0_MEMORY_ENABLED=1 to /etc/hal0/api.env:

   echo 'HAL0_MEMORY_ENABLED=1' | sudo tee -a /etc/hal0/api.env

2. Restart the API so create_app constructs the memory provider:

   sudo systemctl restart hal0-api

3. Confirm it’s wired. The graph status endpoint now responds with real state instead of degrading:

   hal0 memory graph status

When the flag is set, hal0 builds the memory provider from your config. The engine is Hindsight; if the Hindsight daemon is unreachable at startup, hal0 logs a warning and degrades to an in-memory PgVector fallback rather than failing startup.

Caution

The PgVector fallback is volatile — every write is lost on restart. It exists so the tools and dashboard keep answering (empty results instead of a crash) while Hindsight is down, not as a durable substitute. Check GET /api/memory/engine — "engine": "hindsight" and "reachable": true means you’re on the real store; "engine": null means you’re on the volatile fallback.

The graph-extraction gate

Storing recall items is one thing; running an LLM over them to extract a knowledge graph is heavier and separately gated, and it’s off by default even on a fresh install. Control it with the hal0 memory graph sub-app (a thin client over /api/memory/graph).

Hindsight builds its graph natively from whatever local llm slot you point it at — there’s no external-upstream routing anymore. That slot is [memory.graph].extraction_slot in hal0.toml (default "utility"); changing it repoints Hindsight’s extraction LLM and restarts hindsight-api to apply it.

Live memory and graph-extraction dashboard in hal0.

Status

hal0 memory graph status
hal0 memory graph status --json

Shows whether extraction is on, the configured extraction slot (and whether it currently resolves to a live enabled llm slot), the available slots you could pick instead, and counters (builds OK, errors, in-flight, last build / error).

Enable

# turn extraction on, keeping the current extraction slot
hal0 memory graph enable

# turn extraction on and repoint it at a specific local slot
hal0 memory graph enable --slot utility
hal0 memory graph enable --slot agent

--slot names a local type=llm slot; it must already be enabled — the server validates the choice against the live enabled-slot set and rejects an unknown or non-llm slot before it ever reaches hal0.toml. On success it restarts hindsight-api so its extraction LLM actually follows the change. Omit --slot to flip enabled without touching the current slot.

Disable

hal0 memory graph disable

Turns extraction off and cancels any in-flight build. Vector recall is 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:

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.

Caution

Migration is dry-run only today — it reports the plan without writing. Passing --no-dry-run exits with a “not yet implemented” error.

Destructive ops are audited

Every destructive call under /api/memory/* — bank delete, and the memories / config / document / directive / operation / mental-model delete routes, plus the namespace POST /api/memory/delete used for id-scoped deletes — records a durable audit row (actor, target, and a truthful outcome) so a memory wipe is attributable after the fact. Deleting a whole bank additionally requires an explicit confirmation that echoes the bank id back, via ?confirm=<bank_id> (or {"confirm": "<bank_id>"} in the body) — a plain DELETE with no confirmation is rejected with memory.confirm_required.

Related

• Run agents — agents are the main consumer of the memory store.
• MCP tools — the memory_* tool tiers and the /mcp/memory server this guide’s flag gates.