@bcmyguest/openmem 0.6.3 → 0.8.0

package/docs/mem0.md

@@ -15,7 +15,7 @@ Upstream project: [mem0ai/mem0](https://github.com/mem0ai/mem0). Stack details f
 | Bind so the indexer container can reach the server | Wizard smoke: docs, retain, search, delete-by-id |
 | | Unified MCP + optional native mem0 MCP |
 
-Compose profile `mem0` adds env + `extra_hosts` on the shared **indexer** only — there is no mem0 container in this repo yet.
+Compose profile `mem0` adds env + `extra_hosts` on the shared **indexer** only — there is no mem0 container in this repo yet. The optional profile `litellm` adds the stack LiteLLM on loopback for mem0's LLM ([below](#models-through-the-stack-litellm-optional)).
 
 ## First-time setup
 
@@ -55,6 +55,44 @@ curl -fsS "$MEM0_API_URL/docs"   # URL from wizard / stack .env
 
 Search fails if the server’s embedder is misconfigured; smoke stores with `infer: false` and looks for that fact.
 
+## Models through the stack LiteLLM (optional)
+
+mem0 picks its own LLM and embedder. The wizard can instead route mem0's LLM through the stack's LiteLLM, the gateway Hindsight uses, so a model change (Claude included) is one LiteLLM route. In step 3 answer yes to "Route mem0's LLM through the stack LiteLLM", or run `./setup --yes` with `MEM0_LITELLM=1`.
+
+| Backend | mem0 LLM (`memory-llm`) | Embeddings (`memory-embed`) | Key in `litellm.env` |
+| --- | --- | --- | --- |
+| Ollama | `ollama_chat/<model>` (default `gemma4:e2b`) | `ollama/nomic-embed-text` by default (`none` keeps mem0's embedder) | none |
+| Custom OpenAI-compatible URL | `openai/<model>` | optional `openai/<model>` (e.g. `text-embedding-3-small`) | `LEMOND_API_KEY` (same variable as Hindsight's custom route) |
+| Anthropic API key | `anthropic/<model>` (default `claude-haiku-5-5`) | none: mem0 keeps its own embedder | `ANTHROPIC_API_KEY` |
+| Claude subscription (Meridian) | `anthropic/<model>` at Meridian ([guide](meridian-litellm.md)); use is governed by Anthropic's [Consumer Terms](https://www.anthropic.com/legal/consumer-terms) | none | `MERIDIAN_API_KEY` |
+
+What the wizard does:
+
+- writes `~/.config/personal-memory/mem0-litellm.yaml` (routes only; keys are `os.environ/…` references) and points `LITELLM_CONFIG` at it;
+- keeps `LITELLM_MASTER_KEY` and provider keys in `~/.config/hindsight/litellm.env` (mode 600; `LITELLM_ENV_FILE` overrides), creating an `sk-` master key when the file is new;
+- sets `COMPOSE_PROFILES=mem0,litellm`. `litellm` has its own compose profile; `providers/mem0/compose.yaml` publishes it on **`127.0.0.1:${MEM0_LITELLM_PORT:-4000}` only** (the wizard keeps 4000 when free, else offers the next free port) and its entrypoint exits unless `LITELLM_MASTER_KEY` starts with `sk-`;
+- prints the mem0 config blocks below. It does **not** edit your mem0 server config.
+
+```json
+{
+  "llm": {"provider": "openai", "config": {"model": "memory-llm", "openai_base_url": "http://127.0.0.1:4000/v1", "api_key": "<LITELLM_MASTER_KEY>"}},
+  "embedder": {"provider": "openai", "config": {"model": "memory-embed", "openai_base_url": "http://127.0.0.1:4000/v1", "api_key": "<LITELLM_MASTER_KEY>"}},
+  "vector_store": {"config": {"embedding_model_dims": 768}}
+}
+```
+
+The `embedder` and `vector_store` blocks appear only when the backend serves embeddings (768 is `nomic-embed-text`'s size). Apply the blocks yourself: `POST /configure` on the REST server with an admin key, or merge them into the dict you pass to `Memory.from_config`.
+
+Why these keys (mem0 `main` at [26cdefb](https://github.com/mem0ai/mem0/tree/26cdefb46600c0fa5953c4b5ee5003c125539fc4)):
+
+- The self-hosted REST server bundles only the `openai`, `anthropic` and `gemini` LLM providers and the `openai` and `gemini` embedders ([server/main.py L62-63](https://github.com/mem0ai/mem0/blob/26cdefb46600c0fa5953c4b5ee5003c125539fc4/server/main.py#L62-L63)), so the snippet uses provider `openai` against LiteLLM rather than mem0's `litellm` provider ([docs](https://docs.mem0.ai/components/llms/models/litellm)), which also passes no base URL to `litellm.completion` ([mem0/llms/litellm.py](https://github.com/mem0ai/mem0/blob/26cdefb46600c0fa5953c4b5ee5003c125539fc4/mem0/llms/litellm.py)).
+- The `openai` LLM uses `openai_base_url` and `api_key` from its config, but switches to OpenRouter when `OPENROUTER_API_KEY` is set ([mem0/llms/openai.py](https://github.com/mem0ai/mem0/blob/26cdefb46600c0fa5953c4b5ee5003c125539fc4/mem0/llms/openai.py), [config](https://docs.mem0.ai/components/llms/config)).
+- The `openai` embedder reads `openai_base_url`, `api_key` and `model` ([mem0/embeddings/openai.py](https://github.com/mem0ai/mem0/blob/26cdefb46600c0fa5953c4b5ee5003c125539fc4/mem0/embeddings/openai.py), [config](https://docs.mem0.ai/components/embedders/config)). Leaving `embedding_dims` unset keeps it from sending a `dimensions` parameter.
+- pgvector's collection size is `vector_store.config.embedding_model_dims` (default 1536, [mem0/configs/vector_stores/pgvector.py](https://github.com/mem0ai/mem0/blob/26cdefb46600c0fa5953c4b5ee5003c125539fc4/mem0/configs/vector_stores/pgvector.py)). A different embedder needs a new collection or re-added memories.
+- `POST /configure` deep-merges the body into the running config and persists it ([server/main.py L332-337](https://github.com/mem0ai/mem0/blob/26cdefb46600c0fa5953c4b5ee5003c125539fc4/server/main.py#L332-L337), `update_config` in `server/server_state.py`).
+
+Limits: `127.0.0.1` reaches LiteLLM only from a mem0 server running on this host; a mem0 server inside another container needs host networking or a different route. Claude has no embedding model, so the Anthropic and Meridian backends route the LLM only. Whether mem0's extraction prompts (JSON `response_format`) work with every routed model is not verified here; test with an `infer: true` add after switching.
+
 ## Banks / scopes
 
 mem0 scopes map to **`user_id`**. OpenMem’s MCP `bank` argument and indexer banks become that `user_id`. Default unified MCP scope is `openmem-mcp` unless tools pass `bank`. Project work should pass the resolved project bank so session noise does not land in the default. See [Concepts — Context and banks](concepts.md#context-and-banks).

package/docs/memory-providers.md

@@ -65,7 +65,7 @@ after meta steps — like asdf plugin install scripts, not reimplemented npm/mem
 
 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; optional `--hindsight-plugin` adds the upstream Hindsight plugin on Hindsight stacks only.
+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
 
@@ -143,7 +143,7 @@ first step); default action is full **configure and start**.
 
 ### Changing provider later
 
-Prefer **`npx @bcmyguest/openmem switch <id> --yes`** (checkout: `npx . switch <id> --yes`) over a full
+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`

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

@@ -16,6 +16,7 @@ Edit the YAML (or a per-machine override) to change models.
 | --- | --- | --- |
 | `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.
 
@@ -51,6 +52,16 @@ Thinking is off on all three aliases in the route YAML (`enable_thinking: false`
 
 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.
@@ -66,6 +77,17 @@ Example hosted reflect model:
 
 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:

package/docs/npx-install.md

@@ -5,7 +5,7 @@ checkout. The package name lives in one place, the `name` field of `package.json
 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
+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).
 
@@ -23,11 +23,12 @@ 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
+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 `npx . …` in a checkout).
+exist only inside a checkout; prefer `npx @bcmyguest/openmem …` (or `node cli/openmem.mjs …` in a checkout).
 
 ### Commands
 
@@ -38,7 +39,8 @@ exist only inside a checkout; prefer `npx @bcmyguest/openmem …` (or `npx . …
 | `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 |
+| `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 |

package/docs/openmem-config.md

@@ -162,7 +162,7 @@ Interactive `./setup` uses this file for **defaults** (Clack pre-selects); your
     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
+  - `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)
@@ -179,7 +179,7 @@ After changing MCP code, re-run `npx @bcmyguest/openmem install-coding-agent --y
 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
+# from a checkout: node cli/openmem.mjs configure --yes
 ```
 
 After a successful configure, the wizard **writes back** `~/.config/personal-memory/config.toml` so

package/docs/quickstart.md

@@ -7,8 +7,8 @@ Get from zero to a running stack in one wizard run. **Choose your memory provide
 | Requirement | Why |
 | --- | --- |
 | Docker + Compose v2 | Runs the stack; your user must run `docker` without sudo |
-| Node.js ≥ 20.12 | CLI and setup wizard |
-| LLM for Hindsight (default provider) | lemond, Ollama, or OpenAI-compatible — wizard wires LiteLLM |
+| Node.js ≥ 24 | CLI, setup wizard, and the session context store (`node:sqlite` with FTS5) |
+| LLM for Hindsight (default provider) | lemond, Ollama, OpenAI-compatible, or a Claude subscription through [Meridian](meridian-litellm.md) — wizard wires LiteLLM |
 | git, curl | Wizard preflight |
 
 Default stack is [Hindsight](hindsight.md). Other providers: wizard or `npx @bcmyguest/openmem providers` ([provider status](provider-status.md)).
@@ -27,9 +27,11 @@ npx @bcmyguest/openmem
 git clone https://github.com/bcmyguest/openmem.git
 cd openmem
 npm install
-npx . setup
+npm run setup
 ```
 
+Run other commands from the checkout with `node cli/openmem.mjs <command>`.
+
 The wizard asks for a memory provider, provider settings, what to index, then starts Docker and runs a smoke test.
 
 Useful variants:
@@ -41,7 +43,9 @@ npx @bcmyguest/openmem configure --yes       # defaults + start, no prompts
 
 Wizard dry-run (what first setup plans — no writes):
 
-![Setup dry-run: npx @bcmyguest/openmem setup --dry-run](https://bcmyguest.github.io/openmem/setup-demo.gif)
+<p align="center">
+<img src="https://bcmyguest.github.io/openmem/setup-demo.gif" alt="Terminal recording of the setup wizard dry run: preflight checks, memory provider, model backend, secrets, sources and stack steps, each planned write printed as a [dry-run] line" width="720" />
+</p>
 
 ## 2. Confirm it is up
 
@@ -52,7 +56,7 @@ curl -fsS http://127.0.0.1:8888/health   # Hindsight default; see wizard output
 
 ## 3. Wire your coding agent (optional)
 
-**Session memory:** `npx @bcmyguest/openmem install-coding-agent --yes` — unified MCP **plus** session hooks for Claude Code, Codex, OpenCode, Cursor CLI (any active provider). Optional `--hindsight-plugin` adds the upstream Hindsight plugin. Not the same as `install-mcp` alone.
+**Session memory** (after step 1 — MCP and hooks need the running stack): `npx @bcmyguest/openmem install-coding-agent --yes` — unified MCP **plus** session hooks for Claude Code, Codex, OpenCode, Cursor CLI (any active provider). On Hindsight, `--provider-plugin` uses the upstream Hindsight plugin hooks instead (one hook set at a time). Not the same as `install-mcp` alone.
 
 **`install-mcp`** merges the **`openmem` unified MCP** (`memory_add`, `memory_search`, `memory_recall`, `memory_reflect`, `memory_consolidate`, `memory_forget` on whichever provider you picked) and, when NotebookLM sync is on, the **NotebookLM MCP**:
 
@@ -61,7 +65,7 @@ npx @bcmyguest/openmem install-mcp --yes
 npx @bcmyguest/openmem install-mcp --yes --notebooklm   # force NotebookLM entry
 ```
 
-Session hooks use the in-repo shim by default; add `--hindsight-plugin` if you also want the upstream Hindsight plugin. Optional native mem0/Cognee MCP: `install-mcp --provider-only`. Full guide: [MCP setup](mcp-setup.md).
+Session hooks use the in-repo shim by default (`[agents] integration = "openmem"`); `--provider-plugin` replaces them with the upstream Hindsight plugin and `--no-provider-plugin` switches back. Optional native mem0/Cognee MCP: `install-mcp --provider-only`. Full guide: [MCP setup](mcp-setup.md).
 
 Restart Cursor Agent after MCP changes. Move memories between providers with [Portable memory (PMM)](memory-portability.md) — `switch` alone does not migrate data.
 
@@ -79,6 +83,7 @@ npx @bcmyguest/openmem doctor
 | `up` / `down` | Start or stop the stack (down keeps data volumes) |
 | `switch <id> --yes` | Change provider (no memory migration) |
 | `doctor` | Validate config without the smoke test |
+| `schedule install` | Refresh configured RSS/OpenAlex feeds hourly with the OS scheduler |
 
 In a checkout, use `npx .` instead of `npx @bcmyguest/openmem`.
 
@@ -97,5 +102,6 @@ Secrets and index config: `~/.config/hindsight/` (and optional `~/.config/person
 - [Portable memory (PMM)](memory-portability.md) — export/import
 - [Architecture](architecture.md) — data flow, indexing, MCP by provider
 - [Index sources](index-sources.md) — git, Obsidian, notes/papers/bookmarks, feed cache
+- [Feed sync](sources-feeds.md) — configure RSS/OpenAlex and schedule refreshes
 - [Install with npx](npx-install.md) — upgrades, troubleshooting
 - [Configuration file](openmem-config.md) — declarative `config.toml`

package/docs/setup-wizard.md

@@ -5,7 +5,7 @@ The wizard is a Node program (`wizard/bin/setup.mjs`). It is exposed as:
 | How you run it | When |
 | --- | --- |
 | `npx @bcmyguest/openmem` / `npx @bcmyguest/openmem setup` | Normal install ([Install with npx](npx-install.md)) |
-| `npx . setup` / `npm run setup` / `./setup` | Git checkout (stack root stays in the repo) |
+| `npm run setup` / `./setup` | Git checkout (stack root stays in the repo); other commands: `node cli/openmem.mjs <command>` |
 
 Interactive runs use [@clack/prompts](https://github.com/bombshell-dev/clack). `--yes` and `--dry-run` skip Clack.
 
@@ -40,8 +40,9 @@ Configure runs these steps in order (provider hooks replace or extend some steps
 | 5 | Sources to index | Writes `~/.config/hindsight/index.yml`; lists sources with a dry indexer run |
 | 6 | NotebookLM sync | Opt-in; Google login when enabled |
 | 7 | Start the stack | Build indexer image if inputs changed; health wait; smoke retain/recall (unless `--no-smoke`) |
-| 8 | Coding-agent plugin | Optional `npx` install for detected CLIs; provider-specific MCP hints |
-| 9 | Validate memory setup | Provider checks + shared validation |
+| 8 | Context management (smart compaction) | Multi-select of the installed agents (Claude Code, OpenCode 1, OpenCode 2). Defaults: saved `[context_proxy.agents]` keys, else `[context_proxy] enabled`, else OpenCode 2 on and the proxy-routed agents off. Saves all four keys to `config.toml`. Claude Code or OpenCode 1 on: writes the proxy key file and store directories, then starts the `context-proxy` compose service. Neither on: stops a running `context-proxy` after step 9, unless an agent still points at it ([Context management](context-management.md)) |
+| 9 | Coding agents (optional) | For detected CLIs (claude, codex, opencode, cursor-agent), offers `install-coding-agent --yes`: unified MCP, OpenMem skill, session hooks; honours `[agents] integration` (OpenMem hooks or the provider plugin) and `[context_proxy.agents]`. Default answer is no |
+| 10 | Validate memory setup | Provider checks + shared validation |
 
 The last line is `wizard: changed=N` (files and containers this run touched). An unchanged re-run prints `changed=0`.
 
@@ -49,7 +50,7 @@ The last line is `wizard: changed=N` (files and containers this run touched). An
 
 | Provider | Step 3 asks for |
 | --- | --- |
-| Hindsight | Model backend: lemond, Ollama (host or compose profile), or custom OpenAI-compatible URL; LiteLLM routes for `memory-retain`, `memory-reflect`, `memory-consolidate` |
+| Hindsight | Model backend: lemond, Ollama (host or compose profile), custom OpenAI-compatible URL, or a Claude subscription through a running Meridian ([guide](meridian-litellm.md#with-the-wizard)); LiteLLM routes for `memory-retain`, `memory-reflect`, `memory-consolidate` |
 | mem0 | Self-hosted REST base URL and API key file path |
 | Cognee | Loopback port and `LLM_API_KEY` for graph build |
 

package/docs/sources-feeds.md

@@ -22,31 +22,18 @@ Then ensure the stack indexer is running. Each run writes markdown files under `
 
 Network use: feed-sync calls public RSS/OpenAlex URLs from the host (not from CI by default).
 
-## Cron / timer (optional)
+`feed-sync` needs Python 3 with PyYAML on the host. On Windows it uses `py -3`, then `python`; on macOS and Linux it uses `python3`, then `python`. Set `PYTHON` to choose a specific executable.
 
-Run sync on a schedule so feeds stay fresh without manual commands:
+## Schedule feed sync (optional)
 
-```ini
-# ~/.config/systemd/user/openmem-feed-sync.timer
-[Unit]
-Description=Refresh openmem feed cache
+Install an hourly job with the current user's native scheduler. The GitHub npx source works before the next npm release includes `schedule`:
 
-[Timer]
-OnCalendar=hourly
-Persistent=true
-
-[Install]
-WantedBy=timers.target
+```sh
+npx --yes github:bcmyguest/openmem schedule install --dry-run
+npx --yes github:bcmyguest/openmem schedule install
+npx --yes github:bcmyguest/openmem schedule remove
 ```
 
-```ini
-# ~/.config/systemd/user/openmem-feed-sync.service
-[Unit]
-Description=openmem feed-sync
-
-[Service]
-Type=oneshot
-ExecStart=/usr/bin/env npx @bcmyguest/openmem feed-sync
-```
+After that release, `npx @bcmyguest/openmem schedule ...` runs the same command from npm.
 
-Enable with `systemctl --user enable --now openmem-feed-sync.timer`.
+OpenMem installs a systemd user timer on Linux, a launchd agent on macOS, or a Task Scheduler task on Windows. The job calls the published npm package through a stable runner in your user config directory. Installation records the Python interpreter with PyYAML, so the job does not depend on your interactive shell's PATH. It runs when your user scheduler is active; the Linux timer catches up after downtime. Re-run `schedule install` if you move or upgrade Node.js or Python.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bcmyguest/openmem",
-  "version": "0.6.3",
-  "description": "OpenMem \u2014 memory interface for coding agents: pluggable providers (Hindsight, mem0, Cognee, \u2026), shared wizard/indexer, multi-format import/export (PMM and more).",
+  "version": "0.8.0",
+  "description": "OpenMem — memory interface for coding agents: pluggable providers (Hindsight, mem0, Cognee, …), shared wizard/indexer, multi-format import/export (PMM and more).",
   "type": "module",
   "license": "Apache-2.0",
   "author": "B Guest",
@@ -40,7 +40,7 @@
   },
   "files": [
     "cli/",
-    "skills/",
+    ".agents/skills/openmem/",
     "wizard/bin/",
     "wizard/lib/",
     "providers/",
@@ -49,6 +49,7 @@
     "indexer/",
     "bin/",
     "sync/",
+    "proxy/",
     "config/*.example",
     "config/index.yml",
     "config/notebooklm.yml",
@@ -71,7 +72,7 @@
     "!**/.pytest_cache"
   ],
   "engines": {
-    "node": ">=20.12.0"
+    "node": ">=24.0.0"
   },
   "publishConfig": {
     "access": "public"

package/providers/cognee/OPERATOR.md

@@ -43,7 +43,7 @@ When `MEMORY_PROVIDER=cognee`:
 
 ```sh
 npx openmem install-mcp --yes --provider-only
-# checkout: npx . install-mcp --yes --provider-only
+# checkout: node cli/openmem.mjs install-mcp --yes --provider-only
 # or during setup: coding-agent step registers the same entry
 ```
 
@@ -74,7 +74,7 @@ v1 MCP is read-only (no add/cognify). Ingest stays with the indexer or curl.
 ```sh
 npx openmem switch cognee --yes
 # later: npx openmem switch hindsight --yes
-# checkout: npx . switch cognee --yes
+# checkout: node cli/openmem.mjs switch cognee --yes
 ```
 
 Updates `wizard.conf` (and `config.toml` `[memory].provider` when present), restarts the stack