@bcmyguest/openmem 0.0.0-stage → 0.8.0

package/docs/notebooklm.md

@@ -0,0 +1,83 @@
+# NotebookLM
+
+Opt-in. Syncs notebooks, sources, notes, and (optionally) chats from Google NotebookLM into **`notebooklm::<notebook slug>`** banks on whichever memory provider you run (**Hindsight, mem0, or Cognee** — same `MEMORY_SINK` / indexer sinks as the project indexer). Each notebook gets one bank; duplicate titles get an ID suffix. The service runs only under the `notebooklm` compose profile, so a plain `docker compose up` never starts it unless that profile is enabled.
+
+Risks:
+
+- The default `client` backend uses the unofficial `notebooklm-py` library (pinned to 0.8.5 with the `markdown` extra). Google can change or block it at any time, and the sync then fails until the library is updated.
+- The stored login is a Google session cookie set. Anyone who reads `~/.config/notebooklm` can act on that Google account. The directory is bind-mounted read-write into the sync container only, and masked from the indexer.
+- Source text and notes are copied into your active memory backend (`notebooklm::*` scope). With Hindsight, retains may invoke the configured model server; mem0/Cognee store chunks via the indexer sink (Cognee runs cognify after each sync batch).
+
+Login happens in **`npm run setup`** when you enable NotebookLM: the wizard installs
+`notebooklm-py` (via `uv`) if needed, opens the Google sign-in browser, then writes
+`NOTEBOOKLM_HOME=~/.config/notebooklm` into the process environment and `wizard.conf`.
+Cookies land in `~/.config/notebooklm/profiles/default/storage_state.json` (bind-mounted
+into the sync container). Re-run setup when Google expires the session.
+
+Manual equivalent (only if you skip the wizard step):
+
+```sh
+mkdir -p ~/.config/notebooklm
+uv tool install 'notebooklm-py[browser]==0.8.5'
+uv tool run --from 'notebooklm-py[browser]==0.8.5' python -m playwright install chromium
+NOTEBOOKLM_HOME=~/.config/notebooklm notebooklm login        # or: ... login --browser-cookies chrome
+NOTEBOOKLM_HOME=~/.config/notebooklm notebooklm auth check --test --json
+```
+
+Enable and start:
+
+1. Create `~/.config/hindsight/notebooklm.yml` with only the keys you change, for example:
+
+   ```yaml
+   enabled: true
+   interval_minutes: 60        # default 60
+   include_notebooks: ["Work*"] # fnmatch globs, case-insensitive; empty means all
+   ```
+
+   Compose refuses to start if this file is missing; create it first (`touch` is enough when there are no changes). Keys merge with `config/notebooklm.yml`; lists and scalars replace the shipped value.
+2. Start the service from the repository:
+
+   ```sh
+   docker compose --profile notebooklm up -d notebooklm
+   docker compose --profile notebooklm logs -f notebooklm
+   ```
+
+Without a login, the service logs the login commands and retries every 15 minutes. With `enabled: false` it sleeps and checks again hourly.
+
+### Coding-agent access (`notebooklmAccess`)
+
+Synced notebooks land in Hindsight banks named `notebooklm::<slug>`. The coding-agent plugin still uses per-repo `coding-agent::*` banks only. Agents can **list/search** NotebookLM banks on demand (no auto-inject) via an opt-in MCP.
+
+**Primary paths** (pick one):
+
+1. **Wizard** — when you enable NotebookLM sync in setup (step 6), the wizard asks whether to allow coding agents to query those banks via MCP (`notebooklm_list_banks` / `notebooklm_search`). Default is yes after sync is enabled. On yes it writes `notebooklmAccess.enabled: true` into a **real** `~/.hindsight/coding-agent.json` (if that path was a symlink to the repo template, it is copied to a regular file first so machine settings never land in `config/coding-agent.json`) and merges a `notebooklm` entry into `~/.cursor/mcp.json`.
+2. **`npx @bcmyguest/openmem install-mcp`** — same enable + MCP merge when NotebookLM is already on (`notebooklm.yml` `enabled: true`) or with `--notebooklm` / `--notebooklm-only`. See [Coding agents and MCP](coding-agents.md).
+
+Restart Cursor Agent after either path. Manual JSON remains a fallback if you skipped the prompt or need to change allowlists later:
+
+```json
+"notebooklmAccess": {
+  "enabled": true,
+  "banks": ["*"]
+}
+```
+
+- `enabled: false` (shipped default) — the NotebookLM MCP exits immediately; setup does not register it.
+- `banks: ["*"]` — every `notebooklm::*` bank; or list slugs / full ids (e.g. `"sitrep-analysis"` or `"notebooklm::sitrep-analysis"`).
+
+MCP tools (stdio server `cli/notebooklm-mcp.mjs`):
+
+| Tool | Purpose |
+| --- | --- |
+| `notebooklm_list_banks` | Allowlisted `notebooklm::*` banks (`bank_id`, `fact_count`) |
+| `notebooklm_search` | Fast full-text list on one allowlisted bank (`bank_id` + `query`; optional `mode=recall` for slow LLM synthesis) |
+
+When `enabled` is true, the wizard or `install-mcp` merges a `notebooklm` entry into `~/.cursor/mcp.json` (does not overwrite `hindsight` or `codegraph`). To run the server by hand:
+
+```sh
+# after enabling notebooklmAccess (wizard, install-mcp, or hand-edit)
+node cli/notebooklm-mcp.mjs
+# or: openmem-notebooklm-mcp
+```
+
+Enterprise backend (`backend: enterprise`): the documented NotebookLM Enterprise REST API lists recently viewed notebooks only. It returns no source or note text, so this backend syncs notebook metadata only. It is untested against a live Enterprise project.

package/docs/npx-install.md

@@ -0,0 +1,172 @@
+# 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 ≥ 24 (`node:sqlite` with FTS5, for the session context store), 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 && npm run setup       # same wizard; also: ./setup
+node cli/openmem.mjs doctor        # any other command
+```
+
+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 `node cli/openmem.mjs …` 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; `--provider-plugin` runs `@vectorize-io/hindsight-coding-agents` instead of OpenMem hooks on Hindsight stacks (saved as `[agents] integration`; `--no-provider-plugin` reverts) |
+| `context <on\|off\|status>` | context management (smart compaction) per agent: saves `[context_proxy.agents]` (`--agents claude-code,opencode1,codex,opencode2`, default all), re-runs `install-coding-agent`, which starts or stops the `context-proxy` service (`--dry-run`); `status` lists each agent, proxy health and pointed agents ([Context management](context-management.md)) |
+| `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); `--provider-plugin` / `--no-provider-plugin` set `[agents] integration`; 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
+# from a checkout: node cli/openmem.mjs 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.