@bcmyguest/openmem 0.0.0-stage → 0.8.0

package/docs/memory-portability.md

@@ -0,0 +1,73 @@
+# Portable memory (PMM)
+
+OpenMem’s **portability layer** moves memories between providers without baking in a vendor dump format. **PMM** (Personal Memory Manifest) is the first interchange format: export what a backend stores, import into another (or the same) provider, and keep a portable copy for backup or “give me my data” requests.
+
+`npx @bcmyguest/openmem switch` rewires the stack only — it does **not** migrate content. Use export → switch → import (or re-index) when you change backends.
+
+Status: **`memory_export` / `memory_import`** on the unified MCP are **beta**. PMM v1 is stable; adapters live under `cli/mcp/export/` (orchestrator: `cli/mcp/portability.mjs`). MCP install: [MCP setup](mcp-setup.md).
+
+## PMM format (version 1)
+
+JSON object, or JSONL with one header line followed by one normalized record per line:
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `pmm_version` | `1` | Schema version |
+| `exported_at` | ISO-8601 string | When the export was taken |
+| `source_provider` | string | `hindsight` \| `mem0` \| `cognee` |
+| `scope` | object | Provider-specific filter (bank, `user_id`, datasets, …) |
+| `records` | array | Normalized memory records (see below) |
+
+Each **record**:
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `id` | string \| null | Provider id when known |
+| `content` | string | Primary text |
+| `metadata` | object | Optional tags, timestamps, provider payload |
+| `scope_key` | string | Bank name, mem0 `user_id`, Cognee dataset, etc. |
+
+Import accepts PMM with `merge_strategy`:
+
+| Strategy | Behavior |
+| --- | --- |
+| `skip_duplicates` (default) | For mem0, skip records whose id or content fingerprint already exists in the same bank |
+| `overwrite` | Re-import all records (may duplicate on backends without idempotent upsert) |
+
+**Cross-provider import** (e.g. PMM from mem0 into Hindsight) is best-effort: we map `content` + `scope_key` into the active provider’s add API; embeddings and graph structure are **not** preserved.
+
+The MCP export currently collects all records in memory before returning them, including with `format: "jsonl"`. Use a bank filter for large stores; the MCP response is not a file stream. Hindsight export reads the memory-list endpoint and does not include knowledge pages, bank configuration, or source documents. Confirm migrated data before switching providers.
+
+## Implementation (orchestrator + adapters)
+
+openmem stays a **meta orchestrator**: PMM shape and import live in `cli/mcp/portability.mjs`; each backend implements **list/map** in `cli/mcp/export/` (`hindsight.mjs`, `mem0.mjs`, `cognee.mjs`). New providers add an adapter and one branch in `cli/mcp/export/index.mjs` — no changes to the MCP tool names agents call.
+
+## Unified MCP tools
+
+On the `openmem` MCP server ([MCP setup](mcp-setup.md), [Architecture](architecture.md)):
+
+```text
+memory_export   { format?: "json"|"jsonl", bank?: string, user_id?: string }
+memory_import   { data: string, merge_strategy?: "skip_duplicates"|"overwrite" }
+```
+
+Example flow (Cursor Agent / any host with the unified server):
+
+1. `memory_export` with `format: "json"` and optional `bank`
+2. `npx @bcmyguest/openmem switch <other> --yes`
+3. `memory_import` with the exported JSON and `merge_strategy: "skip_duplicates"`
+
+Restart Cursor Agent after `npx @bcmyguest/openmem install-mcp --yes`.
+
+## Provider behavior
+
+| Provider | Export | Import |
+| --- | --- | --- |
+| **mem0** | `GET /memories` with `user_id` from `bank` arg (API key from env file) | `POST /memories` per record (`infer: false`) |
+| **Hindsight** | `GET /v1/default/banks` then paginated `GET …/memories/list` per bank (`bank` arg = one bank; omit = all banks) | `POST …/banks/{bank}/memories` per record |
+| **Cognee** | Resolve indexer dataset name from `bank`, `GET /api/v1/datasets`, paginate `GET …/data` (label/name as content; not full file bytes) | `POST /api/v1/add` per record when dataset in scope |
+
+## Related
+
+- [Architecture — provider interface](architecture.md#how-openmem-interfaces-with-providers)
+- [mem0](mem0.md) · [Cognee](cognee.md)

package/docs/memory-providers.md

@@ -0,0 +1,246 @@
+# Pluggable memory providers
+
+This repo ships **one** supported backend: [Hindsight](https://github.com/vectorize-io/hindsight)
+(API + retain/reflect/consolidate, LiteLLM in front of local models). **mem0** and **Cognee** are
+**experimental** plugins (indexer sink, compose profile, wizard hooks, stub tests). Wave 3 hardened
+operator DX (coding-agent steps, secrets, Ollama wiring); live Cognee cognify+search with a small
+local model is not yet a promotion bar — see `docs/WAVE3-orchestrator.md`. Manifests under
+`providers/` show `experimental` vs `supported`.
+
+## Meta setup wizard (what this is — and is not)
+
+`npm run setup` (checkout), `npx @bcmyguest/openmem setup`, or `./setup` is a **meta** wizard: it
+orchestrates **machine-local plumbing** that is the same idea across providers (Docker project,
+ports, indexer sources, smoke “is the API alive?”, coding-agent config file, compose up/down). It does
+**not** replace each provider’s **native** settings UI, CLI, or config format.
+
+| This wizard owns (cross-cutting) | Provider still owns (native) |
+| --- | --- |
+| Pick provider + stack action (configure / up / down) | API keys, org/project ids, mem0 graph settings |
+| Host ports, `HOST_UID`/`HOST_GID`, compose project name | Hindsight retain/reflect models beyond our LiteLLM routes |
+| Shared `index.yml` (what to index) | Provider-specific memory schema, filters, user ids |
+| Wiring Hindsight → LiteLLM proxy (when provider is Hindsight) | mem0 dashboard, cloud vs self-hosted choice |
+| Health/smoke probes declared in manifest | Official provider docs, upgrades, migrations |
+
+When a provider needs extra fields, the manifest should grow **provider-specific wizard steps** (or
+point to “run `mem0 …` / edit `~/.mem0/…`”) — not cram mem0 into Hindsight’s LiteLLM screens.
+
+### Similar patterns elsewhere
+
+These are the usual analogues people mean by “meta setup”:
+
+- **[mise](https://mise.jdx.dev/) / [asdf](https://asdf-vm.com/)** — one CLI to install and select
+  runtimes; each plugin wraps the tool’s own install rules. mise does not replace `.npmrc` or
+  `Cargo.toml`.
+- **[Chezmoi](https://www.chezmoi.io/)** — applies dotfiles from a repo; Vim, Git, and SSH keep their
+  normal config files on disk.
+- **[Supabase CLI](https://supabase.com/docs/guides/cli)** — `supabase start` brings up Postgres,
+  Auth, Studio; each service still has its own env and tuning.
+- **LiteLLM (in this stack)** — meta proxy in front of lemond/Ollama; model servers keep their own
+  configs. `./setup`’s “model backend” step is really “how LiteLLM reaches your LLM,” not a full
+  lemond replacement.
+- **[Home Assistant](https://www.home-assistant.io/)** — core + integrations; Philips Hue still configured
+  in the Hue app, HA only links it.
+- **`npx skills`-style installers** — discover and install artifacts; each skill or package owns its
+  content afterward.
+
+openmem sits in that category: **one front door** for “memory on this machine for coding agents,”
+not a reimplementation of mem0 or Hindsight settings.
+
+Declarative config is **[mise-like](openmem-config.md)**: `~/.config/personal-memory/config.toml`
+plus `./pm` tasks — same *shape* as mise (`[tasks]`, merged config files), different domain.
+
+Provider-specific setup runs via **[wizard hooks](provider-wizard-hooks.md)** (`providers/*/wizard.mjs`)
+after meta steps — like asdf plugin install scripts, not reimplemented npm/mem0 CLIs.
+
+## Layers (what varies per provider)
+
+| Layer | Hindsight today | Should become |
+| --- | --- | --- |
+| **Compose stack** | `litellm`, `hindsight`, `indexer`, optional `notebooklm` | Provider manifest lists services / profiles; shared `indexer` where possible |
+| **Model routing** | LiteLLM + `config/litellm.*.yaml` | Hindsight-specific; other providers may use their own LLM config or none |
+| **Indexer sink** | `bin/hindsight-project-index` → REST `/v1/default/banks/{bank}/memories` | Python **sink** interface; one implementation per provider |
+| **Setup wizard** | Node wizard: preflight, env, smoke retain/recall | Provider manifest: health URL, smoke steps, env file names |
+| **Coding-agent UX** | `@vectorize-io/hindsight-coding-agents` + `coding-agent.json` | Per-provider plugin package or generic adapter |
+
+NotebookLM sync is **orthogonal** to which provider you picked: enable the `notebooklm` profile and the sync container uses the same `MEMORY_SINK` as the indexer (Hindsight, mem0, or Cognee).
+
+Coding-agent session memory uses the **same** in-repo hooks and unified MCP for every provider; on Hindsight stacks `--provider-plugin` swaps the in-repo hooks for the upstream Hindsight plugin (`[agents] integration = "provider"`).
+
+## Provider manifest
+
+Each provider lives under `providers/<id>/manifest.json`. The wizard loads manifests via
+`wizard/lib/providers/registry.mjs`. Fields are intentionally small; expand only when a second
+provider needs them.
+
+- **`status`**: `supported` | `experimental` | `planned`
+- **`compose`**: which services belong to this provider, health check, default host port env var
+- **`indexer`**: env var for API base URL, `sink`, and `sinkDriver` (see the table below)
+- **`codingAgent`**: optional npx package and config template path
+- **`wizard`**: smoke test bank name and HTTP paths (templates may include `{bank}`)
+
+| `indexer` field | Meaning | Required |
+| --- | --- | --- |
+| `apiUrlEnv` | Env var that holds the provider's API base URL for the wizard | Per provider |
+| `sink` | The `MEMORY_SINK` value, which equals the `indexer/sinks/<sink>.py` module name. Must match `^[a-z][a-z0-9_]*$` (the same rule as `indexer/sinks/__init__.py`). | `supported` and `experimental`; optional but validated for `planned` |
+| `sinkDriver` | Human-readable wire-dialect label (for example `hindsight-rest-v1`). It names no module and drives no dispatch. | `supported` and `experimental` |
+
+`scripts/tests/test_provider_manifests.mjs` checks that every `supported` or `experimental` manifest
+with an `indexer.sink` has a matching `indexer/sinks/<sink>.py`.
+
+## Selecting a sink
+
+The indexer picks its provider with `--sink NAME`, falling back to the `MEMORY_SINK` environment
+variable, then `hindsight`. Compose fragments for alternate providers set both `MEMORY_SINK` and
+`MEMORY_API_URL` on the `indexer` service from stack `.env` values.
+
+| Variable | Used by | Meaning |
+| --- | --- | --- |
+| `MEMORY_SINK` | indexer | Sink module name (`indexer.sink` in the manifest). Default `hindsight`. |
+| `MEMORY_API_URL` | indexer, every non-Hindsight sink | Generic API base URL of the provider. |
+| `HINDSIGHT_URL` | indexer, Hindsight sink only | API base URL for Hindsight (default `http://127.0.0.1:8888`). |
+
+`--url` overrides either URL variable. A sink reads its credentials from its own environment
+variables inside `create`, never from the document path.
+
+Provider secrets (for example `MEM0_API_KEY`, `COGNEE_API_KEY`, `LLM_API_KEY`) live in
+`~/.config/personal-memory/<id>.env`, outside the repo, mode 600. A provider's compose fragment loads
+that file through an `env_file` entry with `required: false`, so a stack without the file still
+starts. Secrets do not belong in the stack `.env` or in `wizard.conf`, and the wizard never prints
+them.
+
+### Optional `flush()`
+
+A sink for a provider that ingests asynchronously (`capabilities.async_ingest=True`, for example
+Cognee, where `cognify` builds the graph after `add`) may define `flush(bank: str) -> None`. The
+indexer calls it once per bank after that bank's batch of retains and deletes, so the provider starts
+processing once per batch rather than once per document.
+
+- The call happens only with `--apply`. The indexer calls `flush(bank)` with an explicit bank when the
+  batch retained or deleted at least one document for that bank, **or** when a previous flush for that
+  bank is still pending. A dry run never flushes, and `flush(None)` is never called.
+- A sink must treat `flush(bank)` as "process this bank now", even when its own in-memory bookkeeping
+  says the bank is clean: the indexer may call it from a fresh process in which that bookkeeping is gone.
+- Pending flushes are persisted. Per-document progress is saved to the indexer state file as it goes, so
+  a failed flush (or a run that died after some retains) would otherwise never be retried. For a sink
+  with a `flush`, the bank is recorded under the state key `::flush-pending` (a sorted list of banks)
+  before the first write of a batch and removed after `flush` succeeds. Every `--apply` run flushes the
+  banks it handles that are still pending, even when nothing changed. A bank whose source is no longer
+  indexed is left alone. Sinks without `flush` (Hindsight) never get the key, so their state file is
+  unchanged.
+- `flush` is not part of the `Sink` protocol, so sinks without it (Hindsight among them) still satisfy
+  `isinstance(sink, Sink)` and see no change in behavior. Callers use `sinks.flush_sink(sink, bank)`,
+  which does nothing when the sink has no callable `flush`.
+- A flush error is handled like a retain error: the source is reported as failed, the other sources
+  still run, and the pending marker stays so the next run flushes again.
+- The watcher (`indexer/watch.py`) spawns this same CLI once per source, so flush runs there too. In
+  the indexer container the sink and URL come from `MEMORY_SINK` and `MEMORY_API_URL`.
+
+Default provider id: **`hindsight`**. Change it in **interactive `./setup`** (Clack “Memory provider”,
+defaults to `config.toml` and `wizard.conf`), or set `MEMORY_PROVIDER` for `--yes`. The wizard records
+the choice in `wizard.conf`. Stack **up** / **down** are wizard actions (`--up`, `--down`, or Clack
+first step); default action is full **configure and start**.
+
+### Changing provider later
+
+Prefer **`npx @bcmyguest/openmem switch <id> --yes`** (checkout: `node cli/openmem.mjs switch <id> --yes`) over a full
+interactive setup re-run when you only need to change backends:
+
+- Updates `MEMORY_PROVIDER` in `~/.config/hindsight/wizard.conf`
+- Updates `[memory].provider` in `~/.config/personal-memory/config.toml` when that file exists
+- Unless `--no-stack`: compose down + up for the new provider (with mem0/Cognee readiness checks)
+- Unless `--no-mcp`: runs `install-mcp --provider-only` so Cursor MCP points at the new provider
+
+Switching does **not** migrate memories between backends. The NotebookLM compose profile and
+`notebooklm` MCP entry are left alone. Flags and examples:
+[README — Switch memory provider](../README.md#switch-memory-provider).
+
+## Suggested implementation phases (separate commits)
+
+### Phase A — Registry and docs (this commitset)
+
+- Manifests for `hindsight`, `mem0`, and `cognee` (`supported`).
+- Wizard reads manifest for health/smoke URLs; behavior unchanged for Hindsight.
+- Document extension points (this file).
+
+### Phase B — Indexer sink interface (implemented)
+
+- HTTP retain/delete/health live in `indexer/sinks/`; default sink is `hindsight`.
+- CLI: `--sink <name>` or env `MEMORY_SINK`; non-Hindsight sinks use `MEMORY_API_URL` for the API base.
+- Contract tests: `indexer/tests/sink_contract.py` and `test_sinks.py`. Per-provider bank mapping and compose env: [indexer-sinks.md](indexer-sinks.md).
+
+### Phase D — Compose profiles (implemented for Hindsight)
+
+- `litellm` and `hindsight` use compose profile `hindsight`; the indexer always starts.
+- `./setup` passes `--profile hindsight` on compose commands; `scripts/setup.mjs` writes `COMPOSE_PROFILES=hindsight` into the stack `.env`.
+- Alternate providers layer `providers/<id>/compose.yaml` with their own profile (`MEMORY_SINK`, `MEMORY_API_URL`, `depends_on`).
+
+### Phase C — mem0 and Cognee (Wave 2 + Wave 3 DX)
+
+- mem0 is **URL-only** in v1: the indexer talks to a mem0 server the operator already runs, and this
+  repo ships no mem0 container yet. A mem0 service built from a pinned upstream ref is a follow-up.
+  Operator runbook: `providers/mem0/OPERATOR.md`. Coding-agent: wizard `setupCodingAgent` prints
+  SDK/MCP steps (no fake `pluginPackage`); register Cursor MCP with
+  `npx @bcmyguest/openmem install-mcp --yes` / `npx @bcmyguest/openmem switch mem0 --yes`.
+- Cognee runs in **docker**: a pinned `cognee/cognee` image on a loopback port with a named volume and
+  an optional env file (`~/.config/personal-memory/cognee.env`, mode 600).
+  Operator notes: `providers/cognee/OPERATOR.md`. Coding-agent: REST on the loopback port plus a
+  read-only stdio MCP (`cli/cognee-mcp.mjs`: `cognee_health` / `cognee_search`) registered by
+  `setupCodingAgent` / `npm run install-mcp` when `MEMORY_PROVIDER=cognee`.
+- **Cognee + Ollama:** default endpoints use `host.docker.internal:11434` (host Ollama on the Docker
+  bridge). When this stack’s compose profile `ollama` publishes **loopback-only**
+  (`127.0.0.1:11434`), that default is refused from the Cognee container. Set
+  `PM_COGNEE_OLLAMA_COMPOSE=1` or `MEMORY_OLLAMA_IN_COMPOSE=1` (wizard Clack also detects
+  `MEMORY_OLLAMA_IN_COMPOSE=1` in `wizard.conf`) so defaults become `http://ollama:11434` and attach
+  Cognee to the same Docker network as the `ollama` service. Cognify still needs a model that can
+  emit Cognee’s structured extraction schemas; small local models (for example `gemma4:e2b`) may
+  pass HTTP add/cognify start but never finish the graph — treat as an operator/LLM tuning issue,
+  not a provider status gate.
+- `hindsight`, `mem0`, and `cognee` manifests are **`supported`**; new backends still land as
+  `experimental` until wizard + indexer + smoke are wired.
+- `indexer/sinks/mem0.py` and `indexer/sinks/cognee.py` implementing the sink protocol (Cognee also
+  implements the optional `flush()`).
+- Wizard branch: provider select (Clack) before model backend when multiple providers are supported.
+- Coding-agent story: mem0’s own SDK/plugin or a thin local proxy—document limitations.
+
+### Phase D — Compose profiles
+
+- `docker compose --profile hindsight` vs `--profile mem0` generated or documented from manifests.
+- Avoid duplicating indexer image; only swap `depends_on` and indexer `environment`.
+
+## mem0 notes (non-goals for Phase A)
+
+mem0’s API and deployment model differ from Hindsight banks and retain/reflect aliases. Expect:
+
+- Different **namespace** model instead of `bank` strings.
+- Possibly **no** LiteLLM sidecar in this repo (mem0 cloud or separate compose).
+- Coding-agent integration likely **not** the Hindsight npx package; manifest should name the real install path when known.
+
+## Developer deep dives (repo only)
+
+These stay under `docs/` and are **not** synced to the Starlight site (see `site/scripts/lib/docs.mjs` —
+only user-facing guides like [Architecture](architecture.md) are listed in `PAGES`).
+
+- [Indexer sink drivers](indexer-sinks.md) — `sink` vs `sinkDriver`, env vars, bank/scope mapping for Hindsight, mem0, Cognee
+- [MCP setup](mcp-setup.md) — unified MCP vs `--provider-only` vs NotebookLM MCP
+
+## Index sources
+
+See [index-sources.md](index-sources.md), [sources-feeds.md](sources-feeds.md), [sources-zotero.md](sources-zotero.md), [sources-readwise.md](sources-readwise.md), and [index-sources-roadmap.md](index-sources-roadmap.md).
+
+## Coding-agent session hooks
+
+See [coding-agent-hooks.md](coding-agent-hooks.md), [coding-agent-scopes.md](coding-agent-scopes.md), and `npx @bcmyguest/openmem install-coding-agent`.
+
+## Site and docs
+
+Published pages sync from `docs/*.md` at build time. If you change mermaid in a synced doc (for example `docs/architecture.md`), run `cd site && pnpm render-diagrams` and commit `site/public/diagrams/*.svg`. Then run `SITE_URL=https://bcmyguest.github.io BASE_PATH=/openmem/ pnpm build` in `site/` — the same check as CI and GitHub Pages.
+
+## Adding a provider (checklist)
+
+1. Add `providers/<id>/manifest.json` with accurate `status`.
+2. Implement indexer sink (Phase B+).
+3. Add compose fragment or profile and document ports/env.
+4. Extend wizard: provider selection, provider-specific steps, smoke test.
+5. Document opt-in / agent config for that provider.
+6. Extend `scripts/tests/test_wizard.sh` or add provider-specific tests.

package/docs/meridian-litellm.md

@@ -0,0 +1,198 @@
+# Meridian route (Claude subscription)
+
+Route the three Hindsight aliases through [Meridian](https://github.com/rynfar/meridian), a local proxy that serves a signed-in Claude subscription over the Anthropic Messages and OpenAI Chat Completions APIs. Hindsight still calls `http://litellm:4000/v1`; only the override YAML changes.
+
+```
+hindsight ──openai──▶ litellm:4000 ──anthropic/──▶ host.docker.internal:3456 (Meridian) ──Agent SDK──▶ Claude subscription
+```
+
+Checked against Meridian 1.87.0 docs and LiteLLM docs on 2026-10-29. Nothing below was run end to end; steps marked **unverified** rest on docs alone.
+
+## Prerequisites
+
+| Need | Why |
+| --- | --- |
+| Node.js 22+ | [Meridian quick start](https://github.com/rynfar/meridian#quick-start) |
+| Claude Code CLI, signed in (`claude login`) | Meridian runs requests through the Agent SDK with those credentials. Haiku 5.5 needs Claude Code 2.1.293+ ([Haiku 5.5](https://github.com/rynfar/meridian/blob/main/docs/configuration.md#haiku-55)) |
+| Claude Pro or Max plan | Requests count against plan limits |
+| OpenMem stack set up | `node scripts/setup.mjs` has run once |
+
+## Run Meridian
+
+```sh
+npm install -g @rynfar/meridian
+claude login
+```
+
+Meridian binds `127.0.0.1:3456` by default. The LiteLLM container reaches the host through `host.docker.internal` (`extra_hosts: host-gateway` in `compose.yaml`), which resolves to the Docker bridge address, not loopback, so a loopback-only Meridian is unreachable from the container on Linux. Bind all interfaces and require a key:
+
+| Variable | Value | Source |
+| --- | --- | --- |
+| `MERIDIAN_HOST` | `0.0.0.0` (default `127.0.0.1`) | [Configuration table](https://github.com/rynfar/meridian/blob/main/docs/configuration.md#configuration) |
+| `MERIDIAN_PORT` | `3456` (default) | same |
+| `MERIDIAN_API_KEY` | long random secret. Clients send it as `x-api-key` or `Authorization: Bearer`; `/` and `/health` stay open | [API Key Authentication](https://github.com/rynfar/meridian/blob/main/docs/configuration.md#api-key-authentication) |
+
+`0.0.0.0` also exposes port 3456 on every host interface; firewall it to the Docker bridge if the machine sits on a shared network.
+
+```sh
+install -d -m 700 ~/.config/meridian
+printf 'MERIDIAN_HOST=0.0.0.0\nMERIDIAN_API_KEY=%s\n' "$(openssl rand -hex 32)" > ~/.config/meridian/meridian.env
+chmod 600 ~/.config/meridian/meridian.env
+set -a; . ~/.config/meridian/meridian.env; set +a
+meridian
+```
+
+### Keep it running
+
+Meridian documents a Nix Home Manager user service and a [systemd socket-activation example](https://github.com/rynfar/meridian/blob/main/docs/configuration.md#systemd-socket-activation). For an npm install it ships `bin/meridian-launchd.sh`, a POSIX launcher it documents as usable "as a systemd `ExecStart`" ([Running as a service without drift](https://github.com/rynfar/meridian/blob/main/docs/configuration.md#running-as-a-service-without-drift)); the launcher self-updates at start unless `MERIDIAN_NO_SELF_UPDATE=1`.
+
+The unit below is **unverified** (written from those docs, not tested). Replace `ExecStart` with the output of `echo "$(npm root -g)/@rynfar/meridian/bin/meridian-launchd.sh"`, and set `PATH` so the unit finds the same `node` and `npm` as your shell (nvm and volta installs live outside the systemd default `PATH`).
+
+```ini
+# ~/.config/systemd/user/meridian.service
+[Unit]
+Description=Meridian proxy (Claude subscription)
+
+[Service]
+EnvironmentFile=%h/.config/meridian/meridian.env
+Environment=PATH=/usr/local/bin:/usr/bin:/bin
+ExecStart=/usr/lib/node_modules/@rynfar/meridian/bin/meridian-launchd.sh
+Restart=on-failure
+
+[Install]
+WantedBy=default.target
+```
+
+```sh
+systemctl --user daemon-reload
+systemctl --user enable --now meridian
+loginctl enable-linger "$USER"   # keep it running while logged out
+```
+
+**Docker alternative (unverified).** Meridian publishes no image; build it from the repo (`docker build -t meridian .`) and mount `~/.claude` ([Docker, single account](https://github.com/rynfar/meridian/blob/main/docs/deployment.md#single-account)). The image already sets `CLAUDE_PROXY_HOST=0.0.0.0`. Attach it to the stack network with `docker network connect openmem_default meridian` and use `api_base: http://meridian:3456`; nothing is then published to the host. Set `MERIDIAN_HOST_ID` and persist the volumes listed under [Persistence and host identity](https://github.com/rynfar/meridian/blob/main/docs/deployment.md#persistence-and-host-identity).
+
+## Provider choice: `anthropic/`
+
+| | `anthropic/<model>` → `/v1/messages` | `openai/<model>` → `/v1/chat/completions` |
+| --- | --- | --- |
+| Meridian path | Primary API; Meridian's docs describe LiteLLM on this route (`passthrough` adapter, [Claude Code behind a gateway](https://github.com/rynfar/meridian/blob/main/docs/configuration.md#claude-code-behind-a-gateway)) | Supported; headerless tool loops get a derived session key ([OpenAI-compatible tools](https://github.com/rynfar/meridian/blob/main/docs/agents.md#openai-compatible-tools-open-webui-continue-etc)) |
+| Tool calls (`memory-reflect`) | LiteLLM translates OpenAI `tools` to Anthropic `tool_use` ([function calling](https://docs.litellm.ai/docs/providers/anthropic#functiontool-calling)); Meridian returns calls to the client in passthrough mode ([Passthrough Mode](https://github.com/rynfar/meridian/blob/main/docs/configuration.md#passthrough-mode-and-tool-calling)) | Meridian translates OpenAI tools itself |
+| `reasoning_effort` | LiteLLM maps it to `thinking` (budget 1024/2048/4096, or adaptive + `output_config.effort` on 4.6+ models) ([thinking](https://docs.litellm.ai/docs/providers/anthropic#usage---thinking--reasoning)). Drop it, below | Meridian's handling undocumented |
+| `response_format` | LiteLLM converts it to native `output_format` on models it knows, else to a forced tool call ([structured outputs](https://docs.litellm.ai/docs/providers/anthropic#structured-outputs)). Meridian's handling of `output_format` is **unverified** | Meridian's handling undocumented |
+
+Use `anthropic/`: it is the route Meridian documents for LiteLLM and gives the request shape LiteLLM translates most predictably. Fall back to `openai/<model>` with `api_base: http://host.docker.internal:3456/v1` if retain fails on structured output.
+
+LiteLLM appends `/v1/messages` to `api_base`, so `api_base` has no `/v1` ([Custom API Base](https://docs.litellm.ai/docs/providers/anthropic#custom-api-base)). LiteLLM sends `api_key` as `x-api-key`, which Meridian accepts.
+
+## Thinking and token limits
+
+The shipped `enable_thinking: false` is a llama.cpp chat-template flag; Claude ignores it. Remove it.
+
+| Setting | Behavior through Meridian |
+| --- | --- |
+| Thinking off | Meridian refuses explicit `thinking: disabled` on Haiku 5.5 with HTTP 400 before generation ([Haiku 5.5](https://github.com/rynfar/meridian/blob/main/docs/configuration.md#haiku-55)). Send no thinking parameter; `additional_drop_params: ["reasoning_effort"]` stops LiteLLM generating one from Hindsight's `reasoning_effort` ([Specify params to drop](https://docs.litellm.ai/docs/completion/drop_params#specify-params-to-drop)) |
+| `HINDSIGHT_API_*_MAX_COMPLETION_TOKENS`, LiteLLM `max_tokens` | Ignored by default: the Agent SDK has no output cap, so Meridian does not bound the answer ([Known limitations](https://github.com/rynfar/meridian/blob/main/docs/configuration.md#known-limitations)). Reflect tool calls are never truncated, and output is unbounded |
+| `MERIDIAN_ENFORCE_MAX_TOKENS=1` | Enforces the cap on thinking plus text. With reflect at 2048, adaptive thinking can consume the budget, and a cap that lands mid tool call fails the request. Leave unset |
+| `temperature`, `top_p` | Meridian's Claude docs do not say whether these reach the model; assume ignored (**unverified**). The README's "does not expose … sampling controls" sentence describes the Antigravity CLI backend, not Claude |
+
+## Route file
+
+`~/.config/hindsight/litellm.yaml` replaces the backend route entirely. Model ids must appear in Meridian's `GET /v1/models`; `claude-haiku-5-5` is Meridian's `haiku` default and `claude-sonnet-5-5` appears in its client examples ([Pi](https://github.com/rynfar/meridian/blob/main/docs/agents.md#pi)). Reflect gets the larger model, as in the shipped routes.
+
+```yaml
+# LiteLLM routes for Hindsight, backend: Meridian on the host (Claude subscription).
+# See docs/meridian-litellm.md. MERIDIAN_API_KEY lives in ~/.config/hindsight/litellm.env.
+model_list:
+  - model_name: memory-retain
+    litellm_params:
+      model: anthropic/claude-haiku-5-5
+      api_base: http://host.docker.internal:3456
+      api_key: os.environ/MERIDIAN_API_KEY
+      max_tokens: 4096
+      timeout: 300
+      additional_drop_params: ["reasoning_effort"]
+  - model_name: memory-reflect
+    litellm_params:
+      model: anthropic/claude-sonnet-5-5
+      api_base: http://host.docker.internal:3456
+      api_key: os.environ/MERIDIAN_API_KEY
+      max_tokens: 4096
+      timeout: 300
+      additional_drop_params: ["reasoning_effort"]
+  - model_name: memory-consolidate
+    litellm_params:
+      model: anthropic/claude-haiku-5-5
+      api_base: http://host.docker.internal:3456
+      api_key: os.environ/MERIDIAN_API_KEY
+      max_tokens: 4096
+      timeout: 300
+      additional_drop_params: ["reasoning_effort"]
+
+general_settings:
+  master_key: os.environ/LITELLM_MASTER_KEY
+```
+
+## With the wizard
+
+`./setup` step "3. Model backend" option 4, **Claude subscription (Meridian)**, automates [Route file](#route-file) and [Apply](#apply). It does not install or start Meridian; run it first as in [Run Meridian](#run-meridian).
+
+| Step | What the wizard does |
+| --- | --- |
+| Ask | Meridian URL from the host (default `http://127.0.0.1:3456`, port from `MERIDIAN_PORT` in `~/.config/meridian/meridian.env`) and an optional `MERIDIAN_API_KEY` (blank reuses the environment, `meridian.env`, or `litellm.env`) |
+| Probe | `GET /health` and `GET /v1/models` (with `x-api-key`) from the host, then `/health` on the `docker0` address. Answering on 127.0.0.1 but not on `docker0` means a loopback-only bind: it warns to set `MERIDIAN_HOST=0.0.0.0`. Without `docker0` it states the requirement |
+| Models | Retain and consolidate: `claude-haiku-5-5`, reflect: `claude-sonnet-5-5`, when listed; otherwise the first listed Haiku and Sonnet ids. Unreachable Meridian: the guide defaults |
+| Write | The route file above as `~/.config/hindsight/litellm.yaml` (an existing one is copied to `litellm.yaml.bak-<timestamp>`), `MERIDIAN_API_KEY` in `litellm.env` (mode 600; `placeholder` when Meridian runs without a key), and `[model] backend = "meridian"` in `wizard.conf` and `config.toml` |
+
+Non-interactive: `PM_BACKEND=meridian MERIDIAN_BASE=http://127.0.0.1:3456 MERIDIAN_API_KEY=... ./setup --yes`. `[model.meridian] host` in `config.toml` sets `MERIDIAN_BASE`; `PM_DEFAULT_MODEL` and `PM_REFLECT_MODEL` pick models. `--dry-run` probes and prints the plan without writing. Then run the [Smoke test](#smoke-test); the wizard's host-side probe does not prove the container reaches Meridian through a firewall.
+
+## Apply
+
+```sh
+cd ~/personal-memory   # this checkout
+[ -f ~/.config/hindsight/litellm.yaml ] && cp ~/.config/hindsight/litellm.yaml ~/.config/hindsight/litellm.yaml.bak-$(date +%Y%m%d%H%M%S)
+$EDITOR ~/.config/hindsight/litellm.yaml          # paste the route file
+grep -h '^MERIDIAN_API_KEY' ~/.config/meridian/meridian.env >> ~/.config/hindsight/litellm.env
+node scripts/setup.mjs
+docker compose up -d --force-recreate litellm
+```
+
+`--force-recreate` matters: Compose does not see edits inside the mounted YAML, so a plain `up -d` can keep the old routes. Revert by moving the override aside and rerunning the last two commands.
+
+## Smoke test
+
+LiteLLM publishes no host port; run curl on the stack network (`openmem_default`, from `name: openmem`).
+
+```sh
+set -a; . ~/.config/hindsight/litellm.env; set +a
+net="--network openmem_default --add-host host.docker.internal:host-gateway"
+
+# 1. Meridian reachable from a container, models listed
+docker run --rm $net curlimages/curl -s http://host.docker.internal:3456/health
+docker run --rm $net curlimages/curl -s -H "x-api-key: $MERIDIAN_API_KEY" http://host.docker.internal:3456/v1/models
+
+# 2. Alias answers through LiteLLM
+docker run --rm $net curlimages/curl -s http://litellm:4000/v1/chat/completions \
+  -H "Authorization: Bearer $LITELLM_MASTER_KEY" -H 'Content-Type: application/json' \
+  -d '{"model":"memory-retain","messages":[{"role":"user","content":"Reply with OK."}]}'
+
+# 3. Reflect returns a tool call (expect finish_reason "tool_calls")
+docker run --rm $net curlimages/curl -s http://litellm:4000/v1/chat/completions \
+  -H "Authorization: Bearer $LITELLM_MASTER_KEY" -H 'Content-Type: application/json' \
+  -d '{"model":"memory-reflect","reasoning_effort":"low","messages":[{"role":"user","content":"What is the weather in Paris? Use the tool."}],
+       "tools":[{"type":"function","function":{"name":"get_weather","description":"Weather for a city",
+       "parameters":{"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}}}]}'
+```
+
+Then run a smoke retain and reflect through Hindsight, as for any route change ([Model configuration](model-configuration.md#verify-and-migrate)).
+
+## Caveats
+
+| Topic | Detail |
+| --- | --- |
+| Terms | Subscription use through third-party proxies is governed by Anthropic's [Consumer Terms](https://www.anthropic.com/legal/consumer-terms); see also Claude Code's [Authentication and credential use](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use) |
+| Third-party detection | Meridian reports Claude refusing Pi traffic as third-party ("Third-party apps now draw from your extra usage, not your plan limits") until Pi's prompt fingerprint is scrubbed ([Pi](https://github.com/rynfar/meridian/blob/main/docs/agents.md#pi)). Whether Hindsight's prompts trigger the same is **unverified**; watch Meridian's `/telemetry` |
+| Plan limits | Retain runs on every ingest; indexing a large repo spends plan quota. `GET /v1/usage/quota` shows the windows |
+| Concurrency | Meridian serializes requests that share a session identity and can return `400 This session advanced while the request was waiting` ([Concurrent requests](https://github.com/rynfar/meridian/blob/main/docs/configuration.md#concurrent-requests-to-the-same-session)). Keep `HINDSIGHT_API_LLM_MAX_CONCURRENT=1` (shipped default) |
+| System prompt | Meridian can prepend Claude Code's own system prompt per adapter (SDK feature toggles at `/settings`). An [adapter instance](https://github.com/rynfar/meridian/blob/main/docs/agents.md#adapter-instances) matching `userAgentPrefix: "litellm/"` can turn it off; effect on Hindsight output is **unverified** |
+| Exposure | `MERIDIAN_HOST=0.0.0.0` without `MERIDIAN_API_KEY` gives anyone on the network your subscription |
+| Server tools | Anthropic server tools (`web_search_*`, `web_fetch_*`) return 400 through Meridian; Hindsight does not use them |

package/docs/model-configuration.md

@@ -0,0 +1,106 @@
+# Model configuration
+
+Hindsight never names a model server. It calls the LiteLLM proxy at `http://litellm:4000/v1` with three fixed aliases, and the proxy's YAML maps each alias to a model:
+
+| Alias | Hindsight operation |
+| --- | --- |
+| `memory-retain` | retain (extraction on ingest) |
+| `memory-reflect` | reflect, the base `HINDSIGHT_API_LLM_MODEL`, and mental-model refresh. Needs a model that makes tool calls |
+| `memory-consolidate` | consolidation |
+
+## Shipped routes
+
+Edit the YAML (or a per-machine override) to change models.
+
+| File | Backend | Default split |
+| --- | --- | --- |
+| `config/litellm.lemond.yaml` | lemond on the host | Reflect: Gemma 4 E4B GGUF (`unsloth/`); retain and consolidate: E2B |
+| `config/litellm.ollama.yaml` | Ollama on the host | Used when `MEMORY_BACKEND=ollama`; `gemma4:e4b` needs Ollama newer than 0.20.3 |
+| `~/.config/hindsight/litellm.yaml` (written by `./setup`, backend `meridian`) | Meridian on the host (Claude subscription) | Retain and consolidate: `claude-haiku-5-5`; reflect: `claude-sonnet-5-5`. See [Meridian route](meridian-litellm.md#with-the-wizard) |
+
+**Why reflect uses a larger model:** E2B often returns no usable tool call on Hindsight reflect (`finish_reason=length`). The shipped lemond route uses E4B for `memory-reflect` only. Qwen3.5-4B works as an alternative if you change the route; pick any model that passes a direct tool-call check and a smoke reflect.
+
+## Route selection
+
+| Priority | Path |
+| --- | --- |
+| 1 | `~/.config/hindsight/litellm.yaml` — full override, mounted read-only into the proxy |
+| 2 | `config/litellm.$MEMORY_BACKEND.yaml` — `lemond` (default) or `ollama` |
+
+`scripts/setup.mjs` writes `LITELLM_CONFIG` in the stack `.env`. After changing backend, override, or routes:
+
+```sh
+node scripts/setup.mjs
+docker compose up -d litellm
+```
+
+Optional Ollama backend:
+
+```sh
+MEMORY_BACKEND=ollama node scripts/setup.mjs
+docker compose up -d litellm
+```
+
+## Thinking and token limits
+
+Thinking is off on all three aliases in the route YAML (`enable_thinking: false` / `think: false`) so replies are not empty when Hindsight sends low `reasoning_effort`.
+
+| Layer | Role |
+| --- | --- |
+| LiteLLM `litellm_params.max_tokens` | Default when the client omits `max_tokens` (4096 in shipped routes) |
+| `HINDSIGHT_API_*_MAX_COMPLETION_TOKENS` in `hindsight.env` | Hard cap Hindsight enforces (retain 16384; reflect and consolidation 2048) |
+
+Retain cap must exceed each retain strategy's chunk size (coding-agent strategies use 12000) or Hindsight returns `400 Invalid retain strategy`.
+
+## Retain extraction mode
+
+OpenMem’s shipped `config/hindsight.env.example` sets:
+
+```env
+HINDSIGHT_API_RETAIN_EXTRACTION_MODE=verbatim
+```
+
+**verbatim** keeps each chunk’s text as the memory unit and still calls the retain LLM for entities, time, and location (cheaper than default `concise` fact rewriting). Alternatives: `concise` / `verbose` (LLM facts), `chunks` (no LLM on ingest; pass entities yourself if needed), or `HINDSIGHT_API_LLM_PROVIDER=none` (chunks-only; reflect disabled). Per-bank strategies can override this (the indexer already uses `chunks` for `project-index`).
+
+## Secrets
+
+`~/.config/hindsight/litellm.env` (mode 600): `LITELLM_MASTER_KEY` (Hindsight uses this as `HINDSIGHT_API_LLM_API_KEY`), plus provider keys referenced as `os.environ/NAME` in the YAML.
+
+Example hosted reflect model:
+
+```yaml
+  - model_name: memory-reflect
+    litellm_params:
+      model: anthropic/claude-haiku-4-5
+      api_key: os.environ/ANTHROPIC_API_KEY
+```
+
+Hindsight always sends the alias names above; you do not edit model ids in `hindsight.env` for route changes.
+
+## mem0 through the same LiteLLM
+
+The `litellm` service carries its own compose profile `litellm` next to `hindsight` and `notebooklm`, so Hindsight's stack renders and starts as before. mem0's wizard can enable that profile: LiteLLM then runs without Hindsight, published on `127.0.0.1:${MEM0_LITELLM_PORT:-4000}` only, from `~/.config/personal-memory/mem0-litellm.yaml`, with the same `litellm.env` and master key.
+
+| Alias | mem0 use |
+| --- | --- |
+| `memory-llm` | mem0's LLM (fact extraction and memory updates) |
+| `memory-embed` | mem0's embedder, only for backends with an embedding model (Ollama `nomic-embed-text`, an OpenAI-compatible server) |
+
+Claude (Anthropic API key or Meridian) has no embedding model; with those backends mem0 keeps its own embedder. The mem0 config keys and their sources are in [mem0 — Models through the stack LiteLLM](mem0.md#models-through-the-stack-litellm-optional).
+
+## Verify and migrate
+
+Health check from the compose network:
+
+```sh
+docker compose exec litellm python3 -c "import urllib.request;print(urllib.request.urlopen('http://127.0.0.1:4000/health/liveliness').read())"
+```
+
+Older `hindsight.env` files that pointed at lemond/Ollama directly:
+
+```sh
+node scripts/setup.mjs --migrate-env
+docker compose up -d
+```
+
+Migration rewrites LLM lines to use `http://litellm:4000/v1` and the three aliases; other lines stay as they are.