@bcmyguest/openmem 0.0.0-stage → 0.6.3

package/docs/npx-install.md

@@ -0,0 +1,170 @@
+# Installing with npx
+
+`openmem` is an npm package whose CLI runs the same setup wizard as `./setup` in a
+checkout. The package name lives in one place, the `name` field of `package.json` (the CLI
+command stays `openmem` if you switch to a scoped name such as
+`openmem`; older installs may still see `openmem`).
+
+Requirements: Node ≥ 20.12 (the floor of `@clack/prompts`), Docker with the compose v2
+plugin (`docker compose version`), `curl`. Linux and macOS are supported; there is no
+bash dependency in the CLI (macOS ships bash 3.2).
+
+Wizard phases and flags live in the repository: [docs/setup-wizard.md](setup-wizard.md). Runtime architecture: [architecture.md](architecture.md).
+
+## Install paths
+
+```sh
+npx @bcmyguest/openmem                 # interactive setup, nothing installed globally
+npx @bcmyguest/openmem setup           # same as the bare command
+npx @bcmyguest/openmem configure --yes # non-interactive setup and start
+npx @bcmyguest/openmem up              # start stack
+npx @bcmyguest/openmem install-mcp --yes
+npx @bcmyguest/openmem switch mem0 --yes
+npm i -g openmem            # then: openmem setup | up | down | ...
+# From a git checkout (package not required on the registry):
+git clone https://github.com/bcmyguest/openmem && cd openmem
+npm install && npx . setup          # same wizard; also: npm run setup / ./setup
+```
+
+No global `pm` command is installed: it collides with Android's `pm`. `./pm` and `npm run pm`
+exist only inside a checkout; prefer `npx @bcmyguest/openmem …` (or `npx . …` in a checkout).
+
+### Commands
+
+| Command | What it does |
+| --- | --- |
+| `openmem` / `setup` | interactive setup; extra flags go to the wizard (`--yes`, `--dry-run`, `--no-smoke`, `--rebuild`) |
+| `configure` | non-interactive setup and start (`setup --yes`) |
+| `up` / `down` | start / stop the stack with the saved configuration |
+| `doctor` | validate the configuration without the smoke test |
+| `install-mcp` | merge **openmem** unified MCP (`memory_*`) by default; NotebookLM when sync is on or `--notebooklm`; native mem0/Cognee with `--provider-only`; `--no-unified-mcp` to skip |
+| `install-coding-agent` | `install-mcp` + session hooks for all providers; optional `--hindsight-plugin` runs `@vectorize-io/hindsight-coding-agents` on Hindsight stacks |
+| `wiring` | report `MEMORY_PROVIDER`, API URLs, and `mcp.json` alignment (`--json`) |
+| `switch <provider>` | change `MEMORY_PROVIDER` (optional stack restart + MCP; no data migration) |
+| `providers [--json]` | list the provider manifests shipped in the package with their status |
+| `init [--force] [--dry-run] [--json]` | create or upgrade the stack root without running the wizard |
+| `--version`, `--help` | |
+
+`--version`, `--help` and `providers` touch nothing on disk. Every other command first
+brings the stack root up to date, then runs the wizard.
+
+## Stack root
+
+Under npx the package directory is a read-only, garbage-collected cache, but the wizard
+writes `.env`, `.build-hash` and `compose.override.yaml` and drives compose files and docker
+build contexts relative to its repo root. The CLI therefore keeps a stable, writable
+**stack root**:
+
+```
+${PM_STACK_ROOT:-${XDG_DATA_HOME:-~/.local/share}/personal-memory/stack}
+```
+
+Layout after `openmem init`:
+
+```
+stack/
+  .pm-stack-manifest.json   sha256 of every shipped file as last written (do not edit)
+  compose.yaml              shipped
+  compose.bench.yaml        shipped
+  indexer/  bin/  sync/     shipped (docker build contexts)
+  config/                   shipped templates: *.example, index.yml, notebooklm.yml,
+                            litellm.*.yaml, coding-agent.json
+  providers/<id>/compose*.yaml   shipped provider compose fragments
+  .env  .build-hash  compose.override.yaml  personal-memory.toml  ...   generated: never touched
+```
+
+The wizard code itself (`wizard/`, `scripts/`, provider manifests and hooks) is **not**
+copied: it runs from the package, so `@clack/prompts` resolves from the package's own `node_modules`.
+Per-user config stays where it always was: `~/.config/hindsight/` and
+`~/.config/personal-memory/config.toml`.
+
+### Environment variables
+
+| Variable | Meaning |
+| --- | --- |
+| `PM_STACK_ROOT` | Mutable stack root = the wizard's `ctx.repoRoot` (compose project dir, `.env`, generated files, docker build context). Overrides the default location. |
+| `PM_USE_CHECKOUT=1` | Use the package directory itself as the stack root and copy nothing. Wins over `PM_STACK_ROOT`. A directory containing `.git` next to `cli/` behaves this way automatically. |
+| `PM_PACKAGE_ROOT` | Read-only code root (provider manifests and hooks, `scripts/setup.mjs`, `wizard/lib`), never written to. Set by the CLI; defaults to the package directory. |
+| `PM_PROJECT` | compose project name (default `openmem`). |
+| `XDG_DATA_HOME` | Base for the default stack root (must be absolute). |
+
+`wizard/bin/setup.mjs` and `wizard/bin/pm.mjs` read `PM_STACK_ROOT` and `PM_PACKAGE_ROOT`
+(defaulting both to the checkout root) and export them to child processes. Running them
+directly from inside an npm package directory without `PM_STACK_ROOT` is refused.
+
+## Upgrades
+
+Each command compares the package's shipped files with the stack root using the manifest:
+
+- Missing file: created (restored if it was shipped before).
+- Identical: left alone.
+- On disk equals what the previous version wrote: overwritten with the new version
+  (atomic write: temp file in the same directory, then rename).
+- Modified by you, or present but not tracked, or a symlink: **kept**, reported as
+  `CONFLICT <path>`. The wizard still runs against your version. Merge by hand, or run
+  `openmem init --force`, which overwrites it and saves yours as
+  `<file>.user-<timestamp>.bak`.
+- No longer shipped: left in place and reported as a note.
+- Generated files (`.env`, `.build-hash`, `compose.override.yaml`, `personal-memory.toml`,
+  anything not in the manifest) are never overwritten or deleted.
+
+After an upgrade the wizard's `.build-hash` check rebuilds the images when their sources
+changed.
+
+## Uninstall
+
+```sh
+openmem down                          # stops the stack (docker compose down)
+npm uninstall -g openmem              # if installed globally
+rm -rf "${XDG_DATA_HOME:-$HOME/.local/share}/personal-memory"   # the stack root
+```
+
+`~/.config/hindsight/` (secrets, `index.yml`) and `~/.config/personal-memory/` are kept
+until you delete them yourself.
+
+## Linux and macOS notes
+
+- Linux: the user must be able to run `docker` without sudo. `host.docker.internal`
+  is mapped through `extra_hosts` in `compose.yaml`.
+- macOS: use Docker Desktop or Colima with the compose v2 plugin and allow file sharing
+  for your home directory (the indexer bind-mounts `$HOME` read-only). 
+- Windows is untested; use WSL2.
+
+## Troubleshooting
+
+- `CONFLICT <path>`: see Upgrades. It is a warning; the stack still works.
+- `cannot prepare the stack root`: the directory is not writable. Set `PM_STACK_ROOT` to
+  a writable path.
+- `read-only ... Run it through the CLI`: you ran `wizard/bin/*.mjs` from inside the npm
+  cache. Use `npx @bcmyguest/openmem` or set `PM_STACK_ROOT`.
+- `missing dependencies (@clack/prompts ...)`: reinstall the package (`npm i -g
+  openmem`), or in a checkout run `npm install` at the checkout root.
+- `... is not valid JSON` for `.pm-stack-manifest.json`: delete the manifest; shipped
+  files that differ from the package are then reported as untracked conflicts instead of
+  being overwritten.
+- Port already in use: set `HINDSIGHT_PORT` / `HINDSIGHT_CP_PORT`, or let the wizard pick
+  a free port.
+
+## Maintainers: publishing
+
+Before the first publish (these are human steps; nothing in this repo does them):
+
+1. **License.** The repository ships `LICENSE` (Apache-2.0) and `package.json` matches.
+2. **Public source.** `npm publish --provenance` needs a public GitHub repository.
+3. **Pack gate.** `npm run pack:check` must pass (no operator home paths in shipped files).
+4. **Create the npm package.** Log in with 2FA (`npm login`), then publish `0.1.0` once by
+   hand (`npm publish --access public`). The name `openmem` was verified free on
+   2026-10-19 (so was `openmem`); re-check with `npm view openmem`.
+5. **Trusted publishing.** On npmjs.com, package Settings -> Trusted Publisher -> GitHub
+   Actions: owner `bcmyguest`, repository `openmem`, workflow `release.yml`.
+6. **Release.** Run the *Prepare release* workflow on `main` (or bump `package.json`, tag
+   `vX.Y.Z`, and push the tag). `release.yml` runs CI, then publishes with `--provenance`
+   when the version is not already on npm, then creates the GitHub Release.
+
+Local rehearsal without publishing:
+
+```sh
+npm run pack:check
+npm pack --pack-destination /tmp/pm-pack
+cd "$(mktemp -d)" && npx --yes /tmp/pm-pack/openmem-*.tgz --version
+```

package/docs/openmem-config.md

@@ -0,0 +1,194 @@
+# Mise-like config (`config.toml`)
+
+openmem is a **meta** orchestrator (see [architecture.md](architecture.md) on the site; [memory-providers.md](memory-providers.md) in the repo for contributors). Its
+declarative config is intentionally similar to **[mise](https://mise.jdx.dev/)**:
+
+| mise | openmem |
+| --- | --- |
+| `~/.config/mise/config.toml` + `.mise.toml` | `~/.config/personal-memory/config.toml` + `openmem.toml` |
+| `[tools]` plugins | `[memory] provider = "…"` + `providers/*/manifest.json` |
+| `[env]` | Host ports / compose project under `[stack]` |
+| `[tasks]` | `npx @bcmyguest/openmem up` / `down` / `doctor` / `install-mcp` / `switch` |
+| `mise install` applies config | `npx @bcmyguest/openmem configure --yes` applies config |
+
+We **do not** replace mise (or mem0/Hindsight native config). You can use both: mise installs
+Node/Docker; this file describes **how agent memory runs on this machine**.
+
+## Files
+
+| Path | Purpose |
+| --- | --- |
+| `config/openmem.toml.example` | Shipped template; copy to your user config |
+| `~/.config/personal-memory/config.toml` | **Primary** user config (gitignored on your machine) |
+| `./openmem.toml` | Optional per-checkout overrides (legacy `personal-memory.toml` still loads) |
+| `~/.config/hindsight/wizard.conf` | Last configure run (`MEMORY_PROVIDER`, ports, …); updated when setup applies |
+
+## Precedence
+
+1. CLI flags (`npx @bcmyguest/openmem setup --up`, `--down`, …)
+2. Environment (`MEMORY_PROVIDER`, `PM_BACKEND`, `HINDSIGHT_PORT`, …)
+3. `~/.config/personal-memory/config.toml`
+4. `openmem.toml` / `config/openmem.toml` in the checkout stack root (legacy `personal-memory.toml` names still load)
+5. Existing `wizard.conf` (provider, ports, model backend from the last wizard run)
+
+Interactive `./setup` uses this file for **defaults** (Clack pre-selects); your answers still win.
+
+## Sections
+
+- **`[memory]`** — `provider` id (`hindsight`, future `mem0`, …).
+- **`[stack]`** — compose project name and host ports.
+- **`[wizard]`** — default action (`configure`, `up`, `down`).
+- **`[model]`** — meta **LLM routing** for the Hindsight stack only; other providers add
+  `[memory.<id>]` tables (see `[memory.mem0]` below).
+- **`[memory.mem0]`** — the mem0 provider (URL-only: you run a mem0 REST server, this stack points
+  the indexer at it). Never holds a key.
+
+  ```toml
+  [memory]
+  provider = "mem0"
+
+  [memory.mem0]
+  api_url = "http://127.0.0.1:18888"        # the server as this host sees it
+  # env_file = "~/.config/personal-memory/mem0.env"   # optional; where MEM0_API_KEY lives
+  ```
+
+  `api_url` is resolved as: `MEM0_API_URL`, then `PM_MEM0_API_URL`, then this table, then the stack
+  `.env`, then `wizard.conf`, then the default `http://127.0.0.1:18888`. The indexer container
+  gets the same URL with `127.0.0.1`/`localhost` rewritten to `host.docker.internal`
+  (`MEM0_INDEXER_URL` in the stack `.env`). The API key is written by `./setup` (from
+  `MEM0_API_KEY` under `--yes`, or a prompt) as the single line `MEM0_API_KEY=your-key-here` in the env file
+  (`MEM0_ENV_FILE`, then `env_file`, then `~/.config/personal-memory/mem0.env`; mode 600 in a mode
+  700 directory). You can also create that file by hand; a server run with `AUTH_DISABLED` needs
+  none. The key never goes into the stack `.env`, `wizard.conf` or `config.toml`. A non-default
+  `env_file` is exported to compose as `MEM0_ENV_FILE` for the run; export it yourself when you run
+  `docker compose` by hand.
+- **`[memory.cognee]`** — the Cognee provider (a pinned `cognee/cognee` container on a loopback
+  port, single-user mode, no authentication). Never holds a key.
+
+  ```toml
+  [memory]
+  provider = "cognee"
+
+  [memory.cognee]
+  port = 8766                                         # host port; the container listens on 8000
+  env_file = "~/.config/personal-memory/cognee.env"   # cognify settings (GLiNER/FastEmbed by default)
+  ```
+
+  `port` is resolved as: `COGNEE_PORT`, then this table, then the stack `.env`, then the port
+  saved in `wizard.conf`, then the default `8766`. Both env file locations follow the same order:
+  the variable (`COGNEE_ENV_FILE`, `COGNEE_INDEXER_ENV_FILE`), then `env_file` /
+  `indexer_env_file` in this table, then the stack `.env`, then the defaults
+  `~/.config/personal-memory/cognee.env` and `~/.config/personal-memory/cognee-indexer.env`.
+  The second file is optional and is the one the indexer container reads; it holds only
+  `COGNEE_API_KEY`. A non-default location (`~` is expanded, a relative path is taken relative
+  to the stack root) is written to the stack `.env` as a path, so a plain `docker compose` finds
+  the same files; the file contents never go there. Keep custom files inside
+  `~/.config/personal-memory`: that is the directory hidden from the indexer's read-only `$HOME`
+  mount, and setup warns about a file elsewhere under `$HOME`.
+
+  Documents are stored but not searchable until cognify can run. **Default cognify path** (no
+  API key): local GLiNER extraction + FastEmbed embeddings. `./setup` / `--yes` with no LLM
+  answers writes that block into the env file (mode 600 in a mode 700 directory), merging into
+  any existing file and replacing only the keys it was given; it prints the path and the key
+  names, never a value. Where the answers come from:
+
+  | Variable (environment) | Written to the env file as |
+  | --- | --- |
+  | `PM_COGNEE_LLM_API_KEY`; under `--yes` or `--dry-run` also plain `LLM_API_KEY` | `LLM_API_KEY` |
+  | `PM_COGNEE_LLM_PROVIDER`, `PM_COGNEE_LLM_MODEL`, `PM_COGNEE_LLM_ENDPOINT` | `LLM_PROVIDER`, `LLM_MODEL`, `LLM_ENDPOINT` |
+  | `PM_COGNEE_EMBEDDING_PROVIDER`, `_MODEL`, `_ENDPOINT`, `_DIMENSIONS` | the same names without `PM_COGNEE_` |
+  | `PM_COGNEE_EMBEDDING_API_KEY`; under `--yes` or `--dry-run` also plain `EMBEDDING_API_KEY` | `EMBEDDING_API_KEY` |
+  | `PM_COGNEE_HUGGINGFACE_TOKENIZER` | `HUGGINGFACE_TOKENIZER` |
+  | `PM_COGNEE_GRAPH_EXTRACTOR`, `PM_COGNEE_AUTO_FEEDBACK` | `GRAPH_EXTRACTOR`, `AUTO_FEEDBACK` |
+
+  **Default (GLiNER + FastEmbed)** when no cognify answers are given:
+
+  ```env
+  GRAPH_EXTRACTOR=gliner_demo
+  EMBEDDING_PROVIDER=fastembed
+  EMBEDDING_MODEL=BAAI/bge-small-en-v1.5
+  EMBEDDING_DIMENSIONS=384
+  AUTO_FEEDBACK=false
+  ```
+
+  Compose pins `HF_HOME` / `FASTEMBED_CACHE_PATH` under the `cognee-data` volume so model
+  downloads survive container recreates. Changing embedding dimensions requires rebuilding
+  vectors (prune datasets or recreate the volume).
+
+  **Local Ollama** (LLM + Ollama embeddings): set `PM_COGNEE_LLM_PROVIDER=ollama` (and optionally
+  `PM_COGNEE_LLM_MODEL=...`). The wizard fills in a complete local block when fields are missing:
+
+  ```bash
+  PM_COGNEE_LLM_PROVIDER=ollama PM_COGNEE_LLM_MODEL=llama3.2 ./setup --yes
+  ```
+
+  That writes (defaults only where unset):
+
+  ```env
+  LLM_PROVIDER=ollama
+  LLM_API_KEY=ollama
+  LLM_ENDPOINT=http://host.docker.internal:11434
+  EMBEDDING_PROVIDER=ollama
+  EMBEDDING_MODEL=nomic-embed-text:latest
+  EMBEDDING_ENDPOINT=http://host.docker.internal:11434/api/embed
+  EMBEDDING_DIMENSIONS=768
+  ```
+
+  Ollama LLM + FastEmbed is also valid: set `PM_COGNEE_EMBEDDING_PROVIDER=fastembed` (and model /
+  dimensions) alongside `PM_COGNEE_LLM_PROVIDER=ollama`. Use the bare Ollama host (`…:11434`),
+  not `…:11434/v1` — Cognee's Ollama path appends `/api/generate` itself. **Host Ollama**
+  (listening on the Docker bridge or all interfaces): `host.docker.internal` is correct.
+  **Compose Ollama** published as `127.0.0.1:11434` only (this repo's default): that address is
+  unreachable via `host.docker.internal` — set `PM_COGNEE_OLLAMA_COMPOSE=1` (or reuse
+  `MEMORY_OLLAMA_IN_COMPOSE=1` from a Hindsight Ollama setup) so the wizard writes
+  `http://ollama:11434`, and attach the Cognee container to the same Docker network as the
+  `ollama` service. Slow local models may need `COGNEE_SKIP_CONNECTION_TEST=true` in
+  `cognee.env`. The interactive setup offers GLiNER+FastEmbed (default), Ollama, or an OpenAI
+  key (hidden prompt). Do not type the key into a non-Clack `./setup` prompt — put
+  `LLM_API_KEY` in `cognee.env` (mode 600) by hand (Ollama accepts any non-empty value), or use
+  the UI / `--yes` with `PM_COGNEE_LLM_API_KEY`. Secret variables (including plain `LLM_API_KEY` /
+  `EMBEDDING_API_KEY` / `COGNEE_API_KEY`) are removed from the wizard's environment before it
+  starts docker. Secrets never go into the stack `.env`, `wizard.conf`, `config.toml` or the
+  summary. Authentication is off: `ENABLE_BACKEND_ACCESS_CONTROL` is pinned false in compose and
+  overrides the env file (see `providers/cognee/compose.yaml`).
+- **`[tasks.*]`** — descriptions for `npx @bcmyguest/openmem` / `./pm` (see `wizard/bin/pm.mjs` and
+  `cli/openmem.mjs`). Built-in tasks:
+  - `configure` / `up` / `down` / `doctor` — map to the setup wizard with the matching flags
+  - `install-mcp` — runs `cli/install-memory-mcp.mjs` (NotebookLM MCP on Hindsight; mem0/Cognee
+    with `--provider-only`; merges into `~/.cursor/mcp.json`)
+  - `switch <provider>` — runs `cli/switch-memory-provider.mjs`: sets `MEMORY_PROVIDER` in
+    `wizard.conf`, updates `[memory].provider` in `config.toml` when present
+    (`updatePmConfigProvider`), optionally restarts the stack and re-points provider MCP.
+    Flags: `--yes`, `--dry-run`, `--no-stack`, `--no-mcp`. Does not migrate data between
+    backends. See [README — Switch memory provider](../README.md#switch-memory-provider).
+  - `feed-sync` — runs `cli/feed-sync.mjs` (RSS + OpenAlex → `feeds.out_dir` in `index.yml`).
+  - `install-coding-agent` — unified MCP + session hooks (all providers); optional `--hindsight-plugin`; see
+    [coding-agent hooks](coding-agent-hooks.md).
+
+## MCP (unified `memory_*` tools)
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `PM_MEMORY_ADD_ASYNC` | `true` (implicit) | Hindsight `memory_add` sends `async: true` unless the tool passes `async: false`. Async ingest returns in ~200ms and avoids Cursor/Claude MCP `-32001` timeouts while extraction runs in the background. Set `PM_MEMORY_ADD_ASYNC=false` to force synchronous ingest. |
+
+After changing MCP code, re-run `npx @bcmyguest/openmem install-coding-agent --yes` (or copy the repo into `~/.local/share/personal-memory/agent-runtime`) and **restart** the openmem MCP server in Cursor.
+
+## Apply
+
+```bash
+cp config/openmem.toml.example ~/.config/personal-memory/config.toml
+# edit provider, ports, model backend
+npx @bcmyguest/openmem configure --yes
+# checkout before publish: npx . configure --yes
+```
+
+After a successful configure, the wizard **writes back** `~/.config/personal-memory/config.toml` so
+the file matches what is running (mise-style source of truth).
+
+## Doctor
+
+```bash
+npx @bcmyguest/openmem doctor
+```
+
+Runs the same checks as setup step “Validate memory setup” without mutating the stack.

package/docs/provider-wizard-hooks.md

@@ -0,0 +1,222 @@
+# Provider wizard hooks (sub-wizards)
+
+The meta wizard (`./setup`, `./pm`) owns cross-provider steps. Each **provider plugin** ships a
+**`providers/<id>/wizard.mjs`** module, the same relationship as asdf/mise plugins: the core tool
+runs the plugin's hooks; it does not reimplement Node, Rust, mem0, or a model router.
+
+The meta wizard knows nothing about any one provider. `wizard/lib/run-wizard.mjs`,
+`wizard/lib/ports.mjs` and `wizard/lib/validate-setup.mjs` contain no provider names (a test greps
+for this). A provider that exports no hook for a phase gets a clean no-op for that phase: there is
+no default provider and no fallback implementation.
+
+## Hook API version
+
+`helpers.apiVersion` is `2`. It is bumped when a helper is removed or changes meaning; adding a
+helper does not bump it. Version 1 (the `chooseBackend` helper and `fallback:` argument) is gone.
+The v1 phase names still work unchanged.
+
+## Package root vs stack root
+
+| Field | Env | Meaning | Used for |
+| --- | --- | --- | --- |
+| `ctx.repoRoot` | `PM_STACK_ROOT` | Mutable stack root | compose project dir (`cwd` of every `docker compose` call), `.env`, `compose.override.yaml`, `.build-hash`, generated files |
+| `ctx.packageRoot` | `PM_PACKAGE_ROOT` (default: `repoRoot`) | Read-only code root | `providers/` manifests and hook modules, `scripts/setup.mjs`, `scripts/gen-masks.mjs` |
+
+For a git checkout they are the same directory. For an installed package the integrator passes the
+stack root as `repoRoot` (`runWizard(stackRoot, argv)`) and the package directory through
+`PM_PACKAGE_ROOT`. `runWizard` exports `PM_PACKAGE_ROOT` so child code sees it.
+`PM_PROVIDERS_DIR` overrides the providers directory entirely (tests use it for fake providers).
+Provider code must write only under `ctx.repoRoot` and read bundled files only under
+`ctx.packageRoot`.
+
+## Execution order
+
+```
+meta.preflight
+meta.provider                   pick memory provider (Clack / TOML / --yes)
+provider.init                   quiet: seed ctx defaults (also runs before preflight)
+provider.resolvePorts           host ports (also after the provider is chosen)
+provider.afterProvider
+provider.configureModelRouting  models, keys, logins
+meta.wizardConf                 written unless the provider already saved it
+meta.setupEnv                   indexer state dir, then provider.setupEnv or scripts/setup.mjs
+meta.index                      index.yml
+meta.notebooklm                 optional profile
+provider.beforeStack            compose fragments, migrations
+meta.stack                      build, up, health, provider.afterStackHealthy, then smoke
+meta.codingAgent                generic npx plugin, then provider.setupCodingAgent
+meta.validate                   generic checks, then provider.extendValidation
+meta.syncConfig                 config.toml (provider.configToml sections)
+meta.summary                    provider.summary
+```
+
+**Stack-only actions** (`./setup --up`, `./pm up`) skip the configure phases:
+
+```
+meta.preflight -> meta.provider -> hydrate -> provider.resolvePorts -> provider.beforeStack
+  -> meta.stack -> meta.validate -> meta.summary
+```
+
+**Down** runs `meta.preflight -> meta.stackDown -> meta.summary`. There are no down hooks yet.
+
+## Hook module contract
+
+Path: `providers/<id>/wizard.mjs` (ESM), found through the manifest:
+
+```json
+"wizardHooks": { "module": "wizard.mjs" }
+```
+
+The path must stay inside the provider directory. Every export is an optional
+`async function(ctx, helpers)`; implement only what you need. Hooks marked announced print
+`provider <id>: <phase>` when they run; quiet hooks return a value to the meta wizard.
+
+| Export | Kind | Return | When it runs |
+| --- | --- | --- | --- |
+| `init` | quiet | ignored | Seed provider defaults on `ctx` before anything reads them |
+| `hydrate` | quiet | ignored | Restore provider state from the saved `wizard.conf` |
+| `afterProvider` | announced | ignored | Right after the provider is selected |
+| `configureModelRouting` | announced | ignored | Model backend, API keys, logins. Honor `ctx.skipBackendStep` (Clack already asked) |
+| `resolvePorts` | announced | ignored | Choose free host ports (`helpers.choosePort`, `helpers.resolveHostPort`) |
+| `stackEnv` | quiet | `{ description?, env? }` | What the generic `scripts/setup.mjs` run should print and receive |
+| `setupEnv` | announced | ignored | Replace the generic secrets/env step; call `helpers.runStackSetup` to still run `scripts/setup.mjs` |
+| `beforeStack` | announced | ignored | After env and index, before `docker compose up` |
+| `apiBase` | quiet | string | HTTP base URL when it is not `http://127.0.0.1:<compose.hostPortEnv>` |
+| `smoke` | announced | ignored | Replace the manifest HTTP smoke test |
+| `afterStackHealthy` | announced | ignored | After health, before smoke (e.g. pull compose Ollama models) |
+| `setupCodingAgent` | announced | ignored | After the generic coding-agent plugin step |
+| `extendValidation` | announced | ignored | Push to `ctx.validationErrors` / `ctx.validationChecks`; runs after the generic checks |
+| `configToml` | quiet | `{ stack?, memory?, <table>: {...} }` | Sections for `config.toml`: `stack` merges into `[stack]`, `memory` sub-tables (for example `memory.mem0`) merge into `[memory]` and `provider` there is always set by the wizard, every other key is a table |
+| `summary` | quiet | `{ running?, configFiles?, notes?, logServices? }` | Lines for the closing summary |
+| `clackSetup` | none | `{ env }` | Called by the Clack front end as `(ctxStub, ui, helpers)` |
+| `prepareStackEnv` | script | `{ entries, drop, report }` | Called by `scripts/setup.mjs`; `.env` always gets `HOST_UID`/`HOST_GID` |
+| `migrateEnv` | script | n/a | `scripts/setup.mjs --migrate-env` |
+| `setupNotices` | script | `string[]` | Lines `scripts/setup.mjs` prints at the end |
+
+`prepareStackEnv`, `migrateEnv` and `setupNotices` receive `{ repo, home, env }` (`repo` is the
+stack root) and run in a separate Node process, so they may not use `helpers`.
+
+Unrecognised exports are ignored. Providers must not import `wizard/lib/run-wizard.mjs`; it
+imports them. Everything the meta wizard owns reaches a hook through `helpers`.
+
+## Helpers
+
+`createHelpers()` in `wizard/lib/provider-wizard/helpers.mjs` returns a frozen object. Functions
+that take `ctx` honor `--dry-run` (they print instead of acting).
+
+| Helper | Purpose |
+| --- | --- |
+| `apiVersion` | `2` |
+| `step`, `info`, `ok`, `warn`, `die` | Logging; `die` exits 1 |
+| `problem(ctx, msg)` | `die`, or `warn` in a dry run |
+| `ask`, `confirm` | Prompts (answers come from `ctx.yes` and `PM_*` env when non-interactive) |
+| `act(ctx, desc, cmd, args, {env, cwd})`, `actWithEnv` | Run a command, printed only in a dry run |
+| `commandExists(name)` | PATH lookup |
+| `envValue(file, key)`, `expandHome`, `ensureConfigDir(ctx)` | Paths and wizard.conf reads |
+| `curlGet`, `curlJson`, `curlRequest` | HTTP via curl |
+| `portFree`, `choosePort(ctx, label, port, {envVars})`, `resolveHostPort(ctx, label)` | Ports; `resolveHostPort` reads the manifest `compose.hostPortEnv` and `defaultHostPort` |
+| `composeArgs(ctx, ...rest)` | `docker compose` argv: project, optional `-f` files, optional `--profile` |
+| `saveWizardConf(ctx, extra, {pmSections})` | Write `wizard.conf` (and `config.toml` sections); no-op in a dry run. Always includes `MEMORY_PROVIDER` |
+| `runStackSetup(ctx, opts)` | Run `<packageRoot>/scripts/setup.mjs` against the stack root |
+| `apiBase(ctx)` | The provider's resolved HTTP base URL |
+
+## Manifest fields the meta wizard reads
+
+```json
+"compose": {
+  "profile": "mem0",
+  "files": ["compose.mem0.yaml"],
+  "hostPortEnv": "MEM0_PORT",
+  "defaultHostPort": 8000,
+  "healthService": "mem0",
+  "logServices": ["mem0"]
+},
+"wizard": { "recallHint": "check the server ({compose} logs mem0)" }
+```
+
+- `compose.profile` adds `--profile <name>`; `compose.files` adds `-f` flags after `compose.yaml`
+  and after `compose.override.yaml` when that exists. Both apply to every compose call: `up`,
+  `down`, `build`, `ps`, and the indexer run. Files must be inside the stack root (no absolute
+  paths, no `..`). With neither field the command text is exactly what it was before.
+- `compose.services` is documentation only: `up` is scoped by the profile, not by service list.
+- The API base URL comes from `compose.hostPortEnv` and `defaultHostPort`, or from an `apiBase`
+  hook. `ctx.apiUrl` (`--api-url`) wins over both.
+- `wizard.recallHint` is the error hint when the smoke recall fails. `{compose}` expands to the
+  full compose command prefix and `{project}` to the project name. Without it the generic
+  message uses `compose.logServices` or `compose.healthService`.
+- A provider with no model backend sets none of `MEMORY_BACKEND`, `MEMORY_MODEL`, ...; generic
+  validation does not require them.
+
+## Delegated commands (asdf-style)
+
+A manifest may declare commands the provider owns outright:
+
+```json
+"wizardHooks": {
+  "module": "wizard.mjs",
+  "delegates": {
+    "mem0-login": { "description": "Run mem0 CLI login", "run": ["mem0", "login"] }
+  }
+}
+```
+
+`./pm mem0-login` runs `run` with inherited stdio when that provider is active. Prefer delegates
+over reimplementing provider CLIs in Node.
+
+## Hindsight
+
+Everything about LiteLLM routes, lemond, Ollama, custom OpenAI-compatible backends and the Clack
+model prompts lives in `providers/hindsight/`:
+
+| File | Role |
+| --- | --- |
+| `wizard.mjs` | Thin hook exports; re-exports `prepareStackEnv`, `migrateEnv`, `setupNotices` |
+| `lib/state.mjs` | `ensureState`, backend defaults, `wizard.conf` reads |
+| `lib/model-backend.mjs` | Backend choice (lemond / ollama / custom), reflect model, model pulls |
+| `lib/litellm-routes.mjs` | Write the LiteLLM route file and `hindsight.env`; saves `wizard.conf` |
+| `lib/probe.mjs` | Probe lemond/ollama endpoints and list models |
+| `lib/config.mjs` | `defaultsFromConfig`, `applyConfigEnv`, `configToml` (`[stack]` ports, `[model]`) |
+| `lib/ports.mjs` | `resolvePorts` for the API and control-plane ports |
+| `lib/env-setup.mjs` | `stackEnv`, `setupEnv` (secrets, LiteLLM env) |
+| `lib/stack-env.mjs` | `prepareStackEnv`, `migrateEnv`, `setupNotices` for `scripts/setup.mjs` |
+| `lib/validate.mjs` | Hindsight validation (model backend, route file, ports) |
+| `lib/summary.mjs` | Closing summary lines |
+| `lib/coding-agent.mjs` | seed/materialize `~/.hindsight/coding-agent.json` (real file) and opt-in paths check |
+| `lib/clack.mjs` | `clackSetup`: backend and model prompts for the Clack front end |
+
+Its `wizard.conf` keeps `MEMORY_PROVIDER`, `MEMORY_BACKEND`, `MEMORY_MODEL`, `MEMORY_API_BASE` and
+`MEMORY_REFLECT_MODEL`. The manifest sets `compose.profile: "hindsight"`, so a
+non-Hindsight provider never starts its services.
+
+`configureModelRouting` takes `ctx.skipBackendStep` (`WIZARD_SKIP_BACKEND_STEP=1`) to skip the
+prompts when Clack has already collected the answers.
+
+## Loader
+
+`wizard/lib/provider-wizard/run-steps.mjs`:
+
+- `loadProviderWizard(manifest)`: import `providers/<id>/wizard.mjs`, cached per file; `{}` when absent
+- `callProviderHook(ctx, phase, helpers)`: returns `{ ran, value }`; announces the announced phases
+- `runProviderPhase(ctx, phase, helpers)`: the same, returning whether the hook ran
+- `runDelegatedCommand`, `listDelegateCommands`: manifest `delegates`
+
+## Tests
+
+- `scripts/tests/test_provider_wizard_hooks.mjs`: helpers `apiVersion`, frozen helpers, hook loader,
+  stubbed-helpers tests of the Hindsight `configureModelRouting` (`--yes`, `skipBackendStep`, the
+  three backends), static checks (no provider imports `run-wizard.mjs`; no provider names in the
+  meta files)
+- `scripts/tests/test_provider_manifests.mjs`: manifest schema incl. `compose.profile`/`files`
+- `scripts/tests/test_wizard.sh`: dry-run and real-run scenarios with a docker stub, including a
+  provider with no hooks, a provider with every v2 hook (fixtures in
+  `scripts/tests/fixtures/providers/`, selected with `PM_PROVIDERS_DIR`), and a package-root /
+  stack-root split
+
+## Adding hooks (checklist)
+
+1. Add `wizardHooks.module` (and `compose.*`) to `manifest.json`
+2. Create `providers/<id>/wizard.mjs`; implement only the phases you need
+3. Keep provider state on `ctx` through `init`/`hydrate`; return `configToml`/`summary` data instead of writing in the meta files
+4. Add `delegates` only when a native CLI must run on the host
+5. Document native vs meta ownership in manifest `settings`
+6. Extend the tests and the [add-memory-provider](../.agents/skills/add-memory-provider/SKILL.md) skill