@bcmyguest/openmem 0.0.0-stage → 0.8.0

package/docs/architecture.md

@@ -0,0 +1,245 @@
+# Architecture
+
+OpenMem connects coding agents and a shared indexer to one active [memory provider](provider-status.md). Agents use the stable `memory_*` MCP and session hooks; the indexer writes sources to the same provider. This page shows the full runtime paths and optional integrations. Setup (`npx @bcmyguest/openmem`) configures them but is outside the runtime data path. Switching providers does not migrate memories.
+
+## Overview
+
+Two paths. **A, memory:** sources go through the indexer into one active provider, which agents reach through the `memory_*` MCP and session hooks. **B, context management:** the context proxy (OpenCode 2: a native plugin) keeps each session under `trim_at_tokens` by moving older turns to a local session store that the agent searches; no model call summarizes them. OpenMem parts are tinted.
+
+<p align="center">
+<picture>
+<source media="(prefers-color-scheme: dark)" srcset="https://bcmyguest.github.io/openmem/media/overview-memory-dark.png" />
+<img src="https://bcmyguest.github.io/openmem/media/overview-memory.png" alt="A, memory: sources, OpenMem indexer, one active provider, OpenMem MCP, coding agents with session hooks" width="360" />
+</picture>
+<picture>
+<source media="(prefers-color-scheme: dark)" srcset="https://bcmyguest.github.io/openmem/media/overview-context-dark.png" />
+<img src="https://bcmyguest.github.io/openmem/media/overview-context.png" alt="B, context management: coding agent, context proxy, model API, session store read back over MCP; OpenCode 2 uses a native plugin" width="360" />
+</picture>
+<br />
+<sub>A, memory · B, context management</sub>
+</p>
+
+The sections below show every runtime path and optional integration.
+
+## Runtime data flow
+
+Two paths share one **active provider API** (Hindsight, mem0, or Cognee — never more than one). Setup (`npx @bcmyguest/openmem`) is not on this diagram; see [How openmem interfaces with providers](#how-openmem-interfaces-with-providers).
+
+```mermaid
+flowchart TB
+  subgraph disk["Sources on disk"]
+    GIT[Git repos]
+    OBS[Obsidian vaults]
+    MD[notes · papers · bookmarks]
+    FEED[Feed cache]
+  end
+
+  subgraph compose["Docker Compose"]
+    IDX[indexer]
+    PROV[(Active provider API)]
+    IDX -->|retain / update via sink| PROV
+    LIT[LiteLLM]
+    NLM[NotebookLM sync]
+    LIT -.->|Hindsight stack only| PROV
+    NLM -.->|opt-in profile| PROV
+  end
+
+  LIT --> LLM[(Local or cloud LLM)]
+
+  subgraph host["Host — IDE / coding agents"]
+    AG[Coding agents]
+    UMCP["openmem MCP\n(memory_*)"]
+    SHIM["Session hooks\n(all providers)"]
+    PLG["Hindsight plugin\n(--provider-plugin, replaces hooks)"]
+    PMCP["Provider MCP\nmem0 or Cognee, optional"]
+    NLMCP["NotebookLM MCP\noptional, separate server"]
+  end
+
+  GIT --> IDX
+  OBS --> IDX
+  MD --> IDX
+  FEED --> IDX
+  AG <-->|stdio| UMCP
+  AG <-->|hooks| SHIM
+  AG <-->|optional| PLG
+  SHIM -->|memory_*| UMCP
+  AG <-->|stdio| PMCP
+  AG <-->|stdio| NLMCP
+  UMCP -->|loopback HTTP| PROV
+  PLG -->|loopback HTTP| PROV
+  PMCP -->|loopback HTTP| PROV
+  NLMCP -->|loopback HTTP| PROV
+```
+
+| Path | What moves |
+| --- | --- |
+| **Indexing** | Git, Obsidian, markdown trees, feed cache → indexer → provider HTTP sink (`MEMORY_SINK` from manifest) |
+| **Agents** | Cursor/Claude/Codex → session hooks and/or MCP → same provider API |
+| **Unified MCP** | `install-mcp` registers `openmem` on the host; tools delegate to the active provider |
+| **LiteLLM** | Optional sidecar on Hindsight stacks; also used for **cross-provider reflect synthesis** when `PM_LLM_URL` / stack LiteLLM is reachable (`memory_reflect` on mem0/Cognee) |
+| **NotebookLM sync** | **Opt-in, any active provider.** Background sync writes into `notebooklm::*` via the same indexer sinks (Hindsight / mem0 / Cognee); not the same as the NotebookLM MCP |
+| **Provider MCP** | Native mem0 or Cognee tool names (`install-mcp --provider-only`); same API as unified MCP, different stdio server |
+| **NotebookLM MCP** | Read-only list/search over synced notebooks; separate entry in `mcp.json`, not a memory provider |
+
+Only **one provider** is active at a time (`MEMORY_PROVIDER`). The indexer uses that provider’s HTTP sink (`MEMORY_SINK` / manifest).
+
+## How openmem interfaces with providers
+
+Product framing: [Concepts](concepts.md).
+
+OpenMem connects the indexer, Compose, wizard, and MCP to the selected provider through its manifest and adapter. Provider support levels come from [Provider status](provider-status.md).
+
+```mermaid
+flowchart TB
+  MAN["providers/*/manifest.json"]
+  HOOK["providers/*/wizard.mjs"]
+
+  subgraph cli["openmem CLI"]
+    W[setup / switch / doctor]
+    IM[install-mcp]
+  end
+
+  subgraph compose["Compose runtime"]
+    IDX[indexer container]
+    API[(Active provider HTTP API)]
+    IDX -->|sink driver| API
+  end
+
+  subgraph host["Host runtime"]
+    MCPJ["~/.cursor/mcp.json"]
+    UMCP[openmem-mcp\nmemory-facade]
+    AG[Agents]
+  end
+
+  MAN --> W
+  MAN --> IDX
+  HOOK --> W
+  W -->|env · compose up| compose
+  IM -->|merge server entry| MCPJ
+  MCPJ --> UMCP
+  AG <-->|stdio| UMCP
+  UMCP -->|fetch active provider| API
+```
+
+### Integration layers
+
+| Layer | What it is | Repo location |
+| --- | --- | --- |
+| **Manifest** | Status, compose services, ports, indexer sink id, smoke HTTP templates | `providers/<id>/manifest.json` |
+| **Wizard hooks** | Provider-specific env, keys, smoke, coding-agent notes | `providers/<id>/wizard.mjs` |
+| **Indexer sink** | Poll/vault → retain/update/delete on the provider API | `indexer/` (driver id in manifest, e.g. `hindsight-rest-v1`, `mem0-rest`) |
+| **Unified MCP** | Stable `memory_*` tools → provider HTTP | `cli/mcp/memory-facade.mjs`, `cli/openmem-mcp.mjs` |
+| **Native agent paths** | Session hooks or provider plugin (`[agents] integration`) + optional MCP | `cli/coding-agent/hook-runner.mjs`; optional Hindsight plugin; `cli/mem0-mcp.mjs`, `cli/cognee-mcp.mjs`, NotebookLM |
+
+Adding a provider means a new manifest + hooks + sink driver; agents can keep using **`memory_*`** once the facade implements that backend.
+
+### Runtime wiring (env and config)
+
+| Input | Resolves |
+| --- | --- |
+| `MEMORY_PROVIDER` | Active provider (`wizard.conf`, optional `config.toml`) |
+| Stack `.env` | API URLs, ports, `MEMORY_SINK`, indexer → provider URL |
+| Provider secret files | e.g. `~/.config/personal-memory/mem0.env` (never committed; not written to `mcp.json`) |
+| `~/.config/hindsight/index.yml` | What the indexer watches |
+
+`npx @bcmyguest/openmem switch <id>` updates provider selection and restarts compose; it does **not** migrate memories ([export/import](memory-portability.md) is for that).
+
+### Example: unified MCP on mem0
+
+1. `npx @bcmyguest/openmem switch mem0 --yes` — compose and env point the indexer and unified MCP at `MEM0_API_URL`.
+2. `npx @bcmyguest/openmem install-mcp --yes` — merges the `openmem` server into `~/.cursor/mcp.json` (NotebookLM MCP only if you enabled sync or pass `--notebooklm`).
+3. The agent calls `memory_add` with `{ content: "…", bank: "my-project" }`. The facade sends `POST /memories` with `user_id=my-project` and `infer: false`.
+
+`install-mcp --provider-only` is a **different** stdio server: same mem0 API, but upstream mem0 tool names from `@yeyuan98/mem0-mcp`. NotebookLM MCP is **different again** — search over notebooks synced into Hindsight, not a substitute for mem0/Cognee/Hindsight memory.
+
+### Unified MCP → provider HTTP
+
+The `openmem` MCP server delegates each tool to the **active** provider:
+
+| Unified tool | Hindsight (`HINDSIGHT_URL`) | mem0 (`MEM0_API_URL` + key file) | Cognee (`COGNEE_API_URL`) |
+| --- | --- | --- | --- |
+| `memory_add` | `POST /v1/default/banks/{bank}/memories` | `POST /memories` (`infer: false`, `user_id` from `bank` arg) | `POST /api/v1/add` |
+| `memory_search` / `memory_recall` | `POST /v1/default/banks/{bank}/memories/recall` | `POST /search` with `filters.user_id` | `POST /api/v1/search` |
+| `memory_reflect` | Same recall path | Search + optional LiteLLM synthesis | Search + optional LiteLLM synthesis |
+| `memory_consolidate` | LiteLLM / Hindsight consolidate routes | Skipped (no equivalent) | `POST /api/v1/cognify` |
+| `memory_forget` | `DELETE /v1/default/banks/{bank}` (bank scope) | `DELETE /memories/{id}` | Not exposed yet |
+| `memory_provider_status` | Returns provider id + loopback URL | Same | Same |
+| `memory_export` / `memory_import` | PMM envelope; mem0 list/add — see [Portable memory (PMM)](memory-portability.md) | | |
+
+Default scope key for MCP-created rows: bank / `user_id` **`openmem-mcp`** unless the tool passes `bank`.
+
+### Native agent paths (optional, alongside unified MCP)
+
+| Provider | Session / tools | Install |
+| --- | --- | --- |
+| **All providers** | In-repo session hooks → unified `memory_*` (`[agents] integration = "openmem"`, default) | `install-coding-agent --yes` |
+| **Hindsight (optional)** | `@vectorize-io/hindsight-coding-agents` plugin instead of the session hooks (`integration = "provider"`) | `install-coding-agent --provider-plugin` |
+| **mem0** | `@yeyuan98/mem0-mcp` tools | `install-mcp --provider-only` |
+| **Cognee** | `cognee_health`, `cognee_search` | `install-mcp --provider-only` |
+| **NotebookLM** | `notebooklm_list_banks`, `notebooklm_search` | `install-mcp` when sync enabled or `--notebooklm` |
+
+`install-mcp` merges the **unified** `openmem` server by default (`--no-unified-mcp` to skip).
+
+## How file changes become memory
+
+The indexer does not watch your editor — it watches **configured sources** on disk (poll, inotify, or periodic re-list).
+
+| Source | Detection | What gets sent to the provider |
+| --- | --- | --- |
+| Git repo | Poll every `poll_seconds` (default 60): `HEAD` + tracked-file status | Tree-sitter outlines + text for changed files → **retain** on the active sink |
+| Obsidian vault | inotify; re-index after `vault_quiet_seconds` (default 30) without edits | Vault documents → provider-specific banks |
+| Notes / papers / bookmarks | `notes.paths`, `papers.paths`, `bookmarks.paths`; inotify on `.md` (bookmarks also `.html`, `.txt`) | Markdown (and bookmark exports) → `notes::`, `papers::`, `bookmarks::` banks |
+| Feed cache | `feeds.out_dir` after `npx @bcmyguest/openmem feed-sync` (RSS / OpenAlex) | Generated markdown → `feed::` banks |
+| New sources under scan roots | Re-list every `relist_seconds` (default 600) | Picked up without restarting the stack |
+
+Configuration: `~/.config/hindsight/index.yml` (wizard writes this on first setup). Full source list and examples: [index-sources.md](index-sources.md) · [sources-feeds.md](sources-feeds.md) · [sources-zotero.md](sources-zotero.md) · [sources-readwise.md](sources-readwise.md). Filters such as `optInPaths` in `~/.hindsight/coding-agent.json` can limit which discovered sources are indexed.
+
+Bank prefixes include `coding-agent::`, `obsidian::`, `notes::`, `papers::`, `bookmarks::`, `feed::`, and optional `notebooklm::*`. mem0 uses `user_id` / `agent_id` / `run_id`; Cognee uses **datasets** mapped from indexer banks.
+
+## Industry context
+
+There is **no** cross-vendor standard for agent memory APIs. MCP standardizes tool transport, not memory semantics — each product exposes different tool names and shapes. openmem’s answer is a **stable facade** on your chosen backend so agents keep the same verbs when you switch providers.
+
+## Unified openmem MCP (beta)
+
+`cli/openmem-mcp.mjs` registers as the `openmem` server in `~/.cursor/mcp.json` when you run `install-mcp` (unless `--no-unified-mcp`). It delegates to the active provider:
+
+| Tool | Purpose |
+| --- | --- |
+| `memory_add` | Store text (Hindsight bank, mem0 user scope, Cognee dataset add) |
+| `memory_search` / `memory_recall` | Query memories on the active backend |
+| `memory_reflect` | Session-style context (recall or search + optional LiteLLM) |
+| `memory_consolidate` | Cognee cognify; Hindsight notes; mem0 skip |
+| `memory_forget` | Delete by id (mem0) or drop a Hindsight bank |
+| `memory_provider_status` | Active provider and loopback URL (no secrets) |
+| `memory_export` / `memory_import` | PMM portable format — [Portable memory (PMM)](memory-portability.md) |
+| `memory_project_scope` | Resolve a workspace's bank and hook access (local) |
+| `memory_pages_list` / `memory_pages_search` / `memory_pages_read` | List, search, and read curated knowledge pages (Hindsight; others return `supported: false`) |
+| `memory_capture_initiative` | Record an approved feature plan as a tracked initiative page plus marker memory (Hindsight) |
+| `memory_status` | Async ingest drain state and operation status (Hindsight; mem0 always ready) |
+| `smart_compact_search` | Search a session's SQLite store of every message (FTS5 BM25 `query`, merged with embeddings when present, or a `pattern` regex), filtered by `role` and `in_context`, with `context` neighbouring rows (local files, every provider) — [Context store](context-store.md) |
+| `smart_compact_sql` | One read-only SELECT against a session database, for counts and aggregates (2 s, 200 rows) |
+| `smart_compact_get` | Return the full text of a compressed tool result by blob id, paged at 100k chars (local files, every provider) |
+
+**Session hooks** (all providers) call the unified MCP via `cli/coding-agent/hook-runner.mjs`. Optional [`@vectorize-io/hindsight-coding-agents`](https://www.npmjs.com/package/@vectorize-io/hindsight-coding-agents) replaces them on Hindsight stacks: `--provider-plugin` sets `[agents] integration = "provider"`, removes OpenMem's hooks and keeps the unified MCP; `--no-provider-plugin` switches back. `--hindsight-plugin` was renamed to `--provider-plugin`. See [Coding-agent hooks](coding-agent-hooks.md).
+
+### Other MCP integrations
+
+| Integration | Tools / path | Role |
+| --- | --- | --- |
+| Session hooks | SessionStart / prompt / Stop → `memory_*` | Default in-IDE session memory (all providers) |
+| Hindsight plugin (optional) | Upstream retain / recall / reflect, instead of the session hooks | `--provider-plugin` only |
+| `notebooklm` (`install-mcp`) | `notebooklm_list_banks`, `notebooklm_search` | Opt-in synced notebooks |
+| `mem0` (`--provider-only`) | mem0 REST tools via `@yeyuan98/mem0-mcp` | Native mem0 tool names |
+| `cognee` (`--provider-only`) | `cognee_health`, `cognee_search` | Native Cognee read-only MCP |
+
+## Related
+
+- [Portable memory (PMM)](memory-portability.md) — export/import
+- [MCP setup](mcp-setup.md) — unified and provider-native MCP
+- [Provider status](provider-status.md) — manifest status and ports
+- [mem0 operator guide](mem0.md) — URL-only mem0 setup
+- [Cognee operator guide](cognee.md) — loopback container + LLM env
+- [Configuration file](openmem-config.md) — `config.toml` for provider and stack defaults
+
+Contributor-only guides (wizard phases, hooks, manual compose, [indexer sinks](indexer-sinks.md), [pluggable providers](memory-providers.md)) live under `docs/` in git and are not all published on the site. Day-to-day MCP install is on [MCP setup](mcp-setup.md).

package/docs/assets/README.md

@@ -0,0 +1,10 @@
+# Docs assets
+
+Regenerate the setup demo GIF after wizard output changes:
+
+```sh
+uv run --with pillow python scripts/render-setup-gif.py
+cp docs/assets/setup-demo.gif site/public/setup-demo.gif
+```
+
+The capture uses stubbed `docker`/`curl` and `npx @bcmyguest/openmem setup --dry-run` (via `wizard/bin/setup.mjs`).

package/docs/coding-agent-hooks.md

@@ -0,0 +1,75 @@
+# Coding-agent session hooks (parity)
+
+Hindsight ships session retain/recall/reflect through
+[`@vectorize-io/hindsight-coding-agents`](https://www.npmjs.com/package/@vectorize-io/hindsight-coding-agents).
+openmem routes session work through the **unified MCP** (`memory_*`) for all three backends.
+
+## Capability matrix
+
+| Capability | Hindsight (default shim) | mem0 (session shim) | Cognee (session shim) |
+| --- | --- | --- | --- |
+| retain | yes for supported agent transcripts | yes for supported agent transcripts (`memory_add`) | yes for supported agent transcripts |
+| recall / search | yes | yes (prompt hook → `memory_recall`) | yes |
+| reflect | yes (`memory_reflect` → Hindsight reflect) | search + optional LiteLLM synthesis | search + optional LiteLLM synthesis; raw hits if unavailable |
+| consolidate | yes (Hindsight/LiteLLM routes) | no | yes (`memory_consolidate` → cognify) |
+| bank / scope | Hindsight banks | mem0 `user_id` | Cognee dataset |
+
+Flags live in `cli/coding-agent/capabilities.mjs`; `doctor wiring` and
+`install-coding-agent` read the same table. `npx @bcmyguest/openmem wiring` prints
+which session features work for the active provider.
+
+## Install per agent
+
+```sh
+npx @bcmyguest/openmem install-coding-agent --yes
+```
+
+- **All providers:** unified MCP and [shared skill](../.agents/skills/openmem/SKILL.md), plus session hooks (`cli/coding-agent/hook-runner.mjs`) for Claude Code, Codex, Cursor Agent, and a JavaScript OpenCode plugin: `cli/coding-agent/opencode-plugin.mjs` for OpenCode 1, `cli/coding-agent/opencode2-plugin/` for OpenCode 2 (the installer picks one from `opencode --version`).
+- **Exclusive hook sets:** `[agents] integration` in `~/.config/personal-memory/config.toml` picks one. `openmem` (default) installs the hooks above and removes the upstream Hindsight install: hook entries (commands under `hindsight-coding-agents` / `.hindsight/coding-agents`), the matching OpenCode `plugin` entry, the `hindsight` MCP server when it runs the upstream `dist/mcp-server.js` (Claude Code `~/.claude.json`, Codex `config.toml`, Cursor `mcp.json`), and the `hindsight-coding-agent` skill copies. Upstream writes no MCP or skill for OpenCode. `provider` (`--provider-plugin`, Hindsight only) removes OpenMem's hooks, keeps the unified MCP, and runs `@vectorize-io/hindsight-coding-agents install`. `--no-provider-plugin` switches back; `--hindsight-plugin` was renamed to `--provider-plugin`. Other providers always get OpenMem hooks.
+
+SessionStart output starts with a two-line banner: provider, bank, and the tools to use. It names `memory_pages_search` and `memory_capture_initiative` only when `PROVIDER_CAPABILITIES` marks `knowledge_pages` / `initiatives` for the provider. The same hook writes `sessions/<sid>.json` per [context store](context-store.md); a write failure is ignored. Denied workspaces get no registration.
+
+`/smart-compact`: the installer writes `~/.claude/commands/smart-compact.md`. The prompt hook (Claude Code, Codex, Cursor) and the OpenCode plugin write `sessions/<sid>.force` when the prompt starts with `/smart-compact`, contains `<command-name>/smart-compact</command-name>`, or contains the command body's `openmem:smart-compact` marker; that prompt skips recall. The flag is written even when memory hooks are denied. Claude Code's hook docs say UserPromptSubmit receives the typed `/command args` text; the other two forms cover expanded deliveries.
+
+Cursor hooks live under `hooks` in `~/.cursor/hooks.json` with `version: 1`, as Cursor documents; reinstall moves entries older OpenMem versions wrote at the top level.
+
+See [MCP setup](mcp-setup.md) and [coding agents](coding-agents.md).
+
+Claude Code Stop retention parses ordinary message and tool-use rows. Codex Stop retention is best effort because Codex does not guarantee a stable transcript format. Cursor Stop retention has a bounded adapter for the observed local agent-transcripts JSONL shape (top-level user/assistant role and `message.content` parts). Live Cursor Hook `transcript_path` linkage to that format remains unverified; unknown row shapes are skipped. Cursor recall and explicit `memory_add` remain available. OpenCode retention uses its plugin's session messages API.
+
+### OpenCode 2 plugin
+
+OpenCode 2 does not run OpenCode 1 plugins ([migration guide](https://opencode.ai/v2/docs/build/plugins/migrate-v1/)). `cli/coding-agent/opencode2-plugin/index.js` default-exports a plain `{ id: "openmem", setup }` object. `Plugin.define` from `@opencode/plugin` 2.2.1 returns its argument unchanged, and OpenCode reads the default export's `id` and `setup()` ([Support V1](https://opencode.ai/v2/docs/build/plugins/server/#support-v1)), so the plugin adds no runtime dependency. `setup(ctx)` registers:
+
+| Feature | OpenCode 2 API | Behaviour |
+| --- | --- | --- |
+| Registration | `prompt` / `context` hooks, `session.created` event | Writes `sessions/<sid>.json` on the first hook call per session. In OpenCode 2.2.1 a location's plugins loaded after `opencode run` had created the session, so `session.created` never arrived |
+| Prompt recall | `ctx.session.hook("prompt")` | First prompt: `memory_reflect`; later prompts: `memory_recall` |
+| System context | `ctx.session.hook("context")` | Pushes the session banner onto `event.system`; puts `Personal memory for <bank>:` and the framed recall block in a leading text part of the user message the prompt belongs to, never in `event.system` |
+| Native trim | `ctx.session.hook("context")` | Replaces `event.messages` per [context proxy](context-proxy.md) rules (`cli/coding-agent/context-trim.mjs`) |
+| Native compaction | `ctx.session.hook("compaction")` | Sets `event.result.summary` to the pointer + recall; `[compaction] native = false` disables it |
+| `/smart-compact` | `prompt` hook; `ctx.command.transform` adds a `smart-compact` command | Writes `sessions/<sid>.force`; no recall for that prompt |
+| Retention | `ctx.session.hook("experimental.idle")`; `session.execution.succeeded`, `session.status` idle and `session.idle` events as fallbacks | Reads `ctx.session.context()` and retains the new user/assistant text once per turn |
+
+The access policy matches OpenCode 1: denied workspaces get no registration, recall or retention, but `/smart-compact`, trimming and compression still run. As with the proxy, a trim pointer carries recall only when the session's registration names a bank.
+
+Hindsight Stop hooks submit retains with `async: true` so model extraction runs after the hook returns. A successful queue response advances the transcript cursor; later extraction failures must be checked through Hindsight operations. MCP `memory_add` defaults to async; pass `async: false` to wait for extraction.
+SessionStart hooks use recall instead of reflect. Hindsight startup recall requests `budget: low` and `max_tokens: 1200`; all hook recall output is limited to eight hits and 8000 characters. Explicit `memory_reflect` remains available through the MCP.
+
+Every hook and plugin recall (SessionStart and prompt hooks for Claude Code, Codex and Cursor; the OpenCode 1 and 2 per-prompt recall) is framed as untrusted data with the trim pointer's frame ([format](context-store.md#proxy-inserted-text)): the fixed sentence, then the text in an `<openmem-recall untrusted="true">` block whose inner `openmem-recall` tags are escaped. The 8000-character cap includes the 147-character frame; the SessionStart banner and the OpenCode `Personal memory for <bank>:` label sit outside it. `hookRecallBlock` in `cli/coding-agent/session-facade.mjs` builds it from the shared `recallBlock` (`cli/coding-agent/recall-frame.mjs`). `[compaction] recall` does not affect hook recall.
+
+## Session scopes
+
+Indexer banks map to provider scopes (`coding-agent::repo`, `obsidian::vault`, mem0 `user_id`, Cognee dataset names). Default MCP scope key: `openmem-mcp`. See [coding-agent-scopes.md](coding-agent-scopes.md).
+
+Hook access is configured in `~/.config/personal-memory/coding-agent.json`. With no file,
+hooks are enabled for all workspaces and use the bank derived from the workspace name. A
+malformed or unreadable config denies hook access, as does an event with no workspace path.
+Set `disabled: true` to turn hooks off, or set `optInOnly: true` and list allowed absolute
+workspace prefixes in `optInPaths`. Project banks resolve in this order: longest matching
+prefix in active `index.yml` `banks`, longest matching prefix in this openmem
+config, then the legacy Hindsight `~/.hindsight/coding-agent.json` mapping. Without
+a match, the literal repository directory name is used in `coding-agent::<name>` (case
+preserved). Nested workspace paths resolve to their Git repository root, and linked
+worktrees share the common repository identity. The openmem config owns current
+access and mapping policy; the legacy mapping remains supported for compatibility.

package/docs/coding-agent-scopes.md

@@ -0,0 +1,22 @@
+# Session scopes (banks, user_id, datasets)
+
+One **scope key** is reused across indexer, unified MCP, and (where supported) the coding-agent path.
+
+| Provider | Indexer bank example | MCP `bank` argument | Notes |
+| --- | --- | --- | --- |
+| Hindsight | `coding-agent::my-repo` | same bank string | Personal-memory hooks and MCP use Hindsight banks |
+| mem0 | same bank string | maps to `user_id` | `memory_add` sets `user_id=bank` |
+| Cognee | same bank string | maps to dataset name | See `cognee-dataset-name` in export code |
+
+Default when tools omit `bank`: **`openmem-mcp`**.
+
+Configure what gets indexed in `~/.config/hindsight/index.yml`. Optional filters in
+`~/.hindsight/coding-agent.json` (`optInPaths`) limit which discovered sources are indexed.
+Project bank routing is shared by the indexer and session integrations: the longest
+matching `banks` prefix in the active index config wins, followed by
+`~/.config/personal-memory/coding-agent.json` `mapPathToBank`, then the legacy
+`~/.hindsight/coding-agent.json` mapping. The fallback uses the literal repository
+directory name, preserving case; nested paths resolve to the repository root, and linked
+worktrees use their common repository identity.
+
+Future: `[session]` section in `~/.config/personal-memory/config.toml` may pin a default scope per repo; not required today.

package/docs/coding-agents.md

@@ -0,0 +1,71 @@
+# Coding agents and MCP
+
+Prerequisite: run the wizard (`npx @bcmyguest/openmem`) so a provider stack is up. The MCP server and hooks only forward to that stack. Per-agent support and evidence levels: [Compatibility matrix](compatibility.md).
+
+One entry point for session wiring on **every** provider (unified MCP + in-repo session hooks):
+
+```sh
+npx @bcmyguest/openmem install-coding-agent --yes
+# --provider-plugin / --no-provider-plugin: upstream Hindsight hooks instead of openmem's (saved in config)
+# --no-rtk: skip rtk wiring;  --context-proxy / --no-context-proxy: local context proxy (saved in config)
+# same flags: --dry-run, --agents claude-code,codex,opencode,cursor-cli,hermes,gemini-cli,amp,cline
+```
+
+Persisted choices live in `~/.config/personal-memory/config.toml`:
+
+| Table | Key | Default | Flag |
+| --- | --- | --- | --- |
+| `[agents]` | `integration` = `openmem` \| `provider` | `openmem` | `--provider-plugin`, `--no-provider-plugin` |
+| `[context_proxy]` | `enabled` | `false` | `--context-proxy`, `--no-context-proxy` |
+| `[context_proxy]` | `port` | `4100` | edit the file |
+| `[compaction]` | `native` | `true` | edit the file; OpenCode 2 only (see below) |
+
+The two hook sets are exclusive; see [hook parity](coding-agent-hooks.md#install-per-agent).
+
+**rtk.** When [`rtk`](https://github.com/rtk-ai/rtk) is on `PATH`, the installer runs rtk's own setup per selected agent: `rtk init -g --auto-patch` (Claude Code), `rtk init -g --codex`, `rtk init -g --agent cursor`, `rtk init -g --opencode`. rtk adds PreToolUse-style command rewriting and keeps other hooks; OpenMem's reinstall keeps rtk's entries. `rtk init` is idempotent. `--no-rtk` skips it.
+
+**Context proxy.** `--context-proxy` creates `~/.config/personal-memory/context-proxy.env` (mode 600) with `LITELLM_MASTER_KEY` once and reuses it. Claude Code gets `env.ANTHROPIC_BASE_URL = http://127.0.0.1:<port>` and `env.ANTHROPIC_CUSTOM_HEADERS = x-litellm-api-key: Bearer <key>` in `~/.claude/settings.json`; OpenCode gets `provider.anthropic.options.baseURL = http://127.0.0.1:<port>/v1` and the same header ([OpenCode providers](https://opencode.ai/docs/providers/#base-url)). Claude Code then fails until the proxy runs. The proxy trims long sessions and compresses tool results; typing `/smart-compact` makes the prompt hook flag the next request for a trim. See [Context proxy](context-proxy.md). `--no-context-proxy` removes those keys when they still point at the loopback proxy; the key file stays. Codex stays hook-only. OpenCode 2 is never pointed at the proxy, even with `--context-proxy`; see below.
+
+**OpenCode 1 or 2.** The installer runs `opencode --version`; output naming major 2 or later (OpenCode 2.2.1 prints `opencode v2.2.1`) selects OpenCode 2, and any failure or other output selects OpenCode 1. OpenCode 1 gets the file entry `cli/coding-agent/opencode-plugin.mjs` under `"plugin"`. OpenCode 2 gets the runtime directory `cli/coding-agent/opencode2-plugin` under `"plugins"` ([OpenCode 2 plugin config](https://opencode.ai/v2/docs/plugins/); configured local paths must be directories). Each install removes OpenMem's entry of the other shape, so only one OpenMem plugin loads. On OpenCode 2 the plugin trims context itself in its `context` hook, with the proxy's rules, thresholds (`CONTEXT_TRIM_AT_TOKENS`, `CONTEXT_COMPRESS_OVER_TOKENS`, `CONTEXT_COMPACTION_MAX_CHARS`, read from the environment OpenCode runs in), standing system-prompt instruction (`CONTEXT_STANDING_INSTRUCTION`) and [context store](context-store.md) files: every message goes into the session database `sessions/<sid>.db` through `node:sqlite` (Node ≥ 24). The installer therefore removes any earlier `provider.anthropic` proxy settings and says so in its summary. When OpenCode 2 compacts a session itself, the plugin's `compaction` hook marks every stored message out of context and supplies the `smart_compact_search` pointer plus bounded recall as the summary, so no model call is made. `[compaction] native = false` returns compaction to OpenCode's own summary.
+
+This stages a persistent runtime under `~/.local/share/personal-memory/agent-runtime`, registers the unified MCP globally in Claude Code, Codex, Cursor Agent, and OpenCode, and installs their session hooks. It also copies the [openmem skill](../.agents/skills/openmem/SKILL.md) into each agent's global skill directory. The runtime path stays valid after an `npx` cache cleanup. Re-run the command after upgrading this package to refresh the runtime and skill. See [hook parity](coding-agent-hooks.md).
+
+For Codex, installation sets `sandbox_mode = "workspace-write"` and enables `features.hooks` and `sandbox_workspace_write.network_access` when unset, and preserves explicit values. Codex otherwise defaults to a read-only sandbox without network, which breaks `curl` and package installs. For OpenCode, the plugin and MCP entry go into the existing `opencode.jsonc` or `opencode.json`; unrelated settings and JSONC comments outside the updated fields are retained.
+
+Codex requires review of new or changed non-managed hooks in `/hooks` before they run. [Codex hook documentation](https://developers.openai.com/codex/hooks) describes this trust step.
+
+The command keeps existing agent settings and other MCP servers. With `integration = "openmem"` it removes what the upstream Hindsight plugin installed: its hook entries, its `hindsight` MCP server (`~/.claude.json`, `~/.codex/config.toml`, `~/.cursor/mcp.json`) and its `hindsight-coding-agent` skill (`~/.claude/skills`, `~/.agents/skills`, `~/.cursor/skills`). An MCP entry goes only when it runs the upstream `hindsight-coding-agents/dist/mcp-server.js`; a skill only when its `SKILL.md` declares `name: hindsight-coding-agent`. A `hindsight` MCP entry of your own that points elsewhere stays. `--dry-run` lists the removals; `provider` mode removes none of these.
+
+Wizard step 8 (Coding agents) offers the same `install-coding-agent --yes` for detected CLIs.
+
+Use a **real** `~/.hindsight/coding-agent.json` on disk (seed from `config/coding-agent.json`). Do not symlink into the repo — machine fields such as `optInPaths` and `notebooklmAccess` must not live in the checkout. The indexer reads this file through the `$HOME` mount. If it is missing, the indexer logs a warning and still indexes everything under `$HOME`.
+
+### Memory MCP servers (`~/.cursor/mcp.json`)
+
+To register **only** Cursor's memory-related MCP entries (NotebookLM, mem0, Cognee, and unified `openmem`) without re-running full setup:
+
+```sh
+npx @bcmyguest/openmem install-mcp --yes
+# checkout: node cli/openmem.mjs install-mcp --yes
+
+# mem0 self-hosted REST → @yeyuan98/mem0-mcp via cli/mem0-mcp.mjs
+MEMORY_PROVIDER=mem0 npx @bcmyguest/openmem install-mcp --yes --provider-only
+
+# Cognee read-only health/search → cli/cognee-mcp.mjs
+MEMORY_PROVIDER=cognee npx @bcmyguest/openmem install-mcp --yes --provider-only
+```
+
+Provider comes from `MEMORY_PROVIDER`, else `~/.config/hindsight/wizard.conf`, else `hindsight`. NotebookLM MCP is installed when `~/.config/hindsight/notebooklm.yml` has `enabled: true`, or with `--notebooklm`. Flags: `--dry-run`, `--notebooklm-only`, `--provider-only`. Existing `hindsight` / `codegraph` / `notebooklm` / sibling provider entries are merged, not clobbered. For mem0, `mcp.json` gets `MEM0_API_URL` / `MEM0_BASE_URL` and the path to `mem0.env` — never the API key ([mem0 operator guide](https://github.com/bcmyguest/openmem/blob/main/providers/mem0/OPERATOR.md)). For Cognee, `mcp.json` gets `COGNEE_API_URL` only — never `COGNEE_API_KEY` ([Cognee operator guide](https://github.com/bcmyguest/openmem/blob/main/providers/cognee/OPERATOR.md); tools `cognee_health` / `cognee_search`). Manual JSON edits remain a fallback.
+
+Restart the Cursor Agent (or other coding agent) after install so it loads the new wiring. With `optInOnly: true`, only paths listed in `optInPaths` get memory — `/tmp` workspaces and other unlisted directories stay opted out.
+
+### Switch memory provider
+
+To change `MEMORY_PROVIDER` (updates `~/.config/hindsight/wizard.conf`, optionally restarts the stack and refreshes provider MCP) without a full interactive setup:
+
+```sh
+npx @bcmyguest/openmem switch mem0 --yes
+# checkout: node cli/openmem.mjs switch cognee --yes
+```
+
+Flags: `--dry-run`, `--no-stack` (skip compose down/up), `--no-mcp` (skip `install-mcp --provider-only`). Switching does **not** migrate memories between backends. After a switch: restart Cursor Agent, then `npx @bcmyguest/openmem doctor`.

package/docs/cognee.md

@@ -0,0 +1,37 @@
+# Cognee (loopback container)
+
+Self-hosted graph/RAG memory via a pinned `cognee/cognee` image on a loopback port (`COGNEE_PORT`, default **8766**). Auth is off in this stack. Cognify defaults to local GLiNER + FastEmbed (no API key); optional LLM keys live in env files under `~/.config/personal-memory/`, not in stack `.env` or `mcp.json`.
+
+## Coding agents
+
+No plugin package. Agents use REST (`/docs`, `/health`, `/api/v1/add`, `/cognify`, `/search`) or the **read-only** MCP in this repo.
+
+### Cursor MCP
+
+When `MEMORY_PROVIDER=cognee`:
+
+```sh
+npx @bcmyguest/openmem install-mcp --yes --provider-only
+```
+
+Registers `cli/cognee-mcp.mjs` with `COGNEE_API_URL` only — **never** `COGNEE_API_KEY` in `mcp.json`. If you enable auth, export the key in the agent environment.
+
+| Tool | Purpose |
+| --- | --- |
+| `cognee_health` | `GET /health` |
+| `cognee_search` | `POST /api/v1/search` |
+
+Ingest and cognify stay with the indexer or direct API calls; the MCP is search/health only.
+
+Restart Cursor Agent after install.
+
+## Switch provider
+
+```sh
+npx @bcmyguest/openmem switch cognee --yes
+# later: npx @bcmyguest/openmem switch hindsight --yes
+```
+
+Updates active provider config, restarts the stack (unless `--no-stack`), runs MCP install (unless `--no-mcp`). Does **not** migrate memories.
+
+See also [Architecture](architecture.md), [Hindsight](hindsight.md), and [Provider status](provider-status.md).

package/docs/compatibility.md

@@ -0,0 +1,80 @@
+# Compatibility matrix
+
+What OpenMem supports per coding agent and per memory provider, as of branch `feat/openmem-context-layer` (2026-10-29). Each cell records the strongest evidence that exists, not intent.
+
+| Mark | Meaning |
+| --- | --- |
+| ✅ | Verified live against a real agent or server |
+| 🧪 | Implemented and covered by automated tests; not yet verified live |
+| ◐ | Partial or best effort; see the note |
+| ❌ | Not supported |
+
+## Coding agents
+
+`install-coding-agent` wires the first five columns. Hermes, Gemini CLI, Amp and Cline get the unified MCP through `install-mcp` and their own MCP configuration; nothing else.
+
+| Feature | Claude Code | Codex CLI | Cursor CLI | OpenCode 1.x | OpenCode 2.x |
+| --- | --- | --- | --- | --- | --- |
+| Unified `memory_*` MCP | 🧪 ¹⁴ | 🧪 | 🧪 ¹⁴ | 🧪 ¹⁴ | ❌ ¹ |
+| OpenMem skill | 🧪 | 🧪 | 🧪 | 🧪 | ❌ ¹ |
+| Startup banner + recall | 🧪 | 🧪 ² | 🧪 ³ | 🧪 ²² | 🧪 ¹⁵ ²² |
+| Session registration (`sessions/<sid>.json`) | 🧪 | 🧪 | 🧪 ³ | 🧪 ⁴ | ✅ ¹⁵ ¹⁶ |
+| Per-prompt recall | 🧪 | 🧪 | 🧪 ³ | 🧪 | ✅ ¹⁵ |
+| Turn retention (Stop / idle) | 🧪 | ◐ ⁵ | ◐ ⁶ | 🧪 | ✅ ¹⁵ ¹⁷ |
+| `/smart-compact` trim flag | 🧪 ⁷ | 🧪 | 🧪 | 🧪 | ✅ ¹⁵ ¹⁸ |
+| Context proxy (trim, tool-result compression) | ✅ ⁸ | ✅ ⁹ | ❌ ¹⁰ | ◐ ¹¹ | ✅ native ¹⁵ ¹⁹ |
+| Agent compaction replaced by pointer + recall | ❌ | ❌ | ❌ | ❌ | ✅ ¹⁵ (`[compaction] native`) |
+| `[agents] integration` toggle | 🧪 ²¹ | 🧪 ²¹ | 🧪 ²¹ | 🧪 ²¹ | 🧪 ²⁰ |
+| rtk command rewriting (`rtk init`) | 🧪 ¹² | 🧪 ¹² | 🧪 ¹² | 🧪 ¹² | ❌ ¹³ |
+
+1. Not built for OpenCode 2. OpenCode 2 replaced the plugin API ([migration guide](https://opencode.ai/v2/docs/build/plugins/migrate-v1/)) and its config shape (`"plugins"`, `"providers"`); the installer's MCP and skill wiring for OpenCode was written for OpenCode 1 and has not been checked against OpenCode 2.
+2. Codex runs non-managed hooks only after review in `/hooks` ([Codex hooks](https://developers.openai.com/codex/hooks)).
+3. Cursor hooks now go under `"hooks"` in `~/.cursor/hooks.json` (Cursor's documented shape). Earlier OpenMem releases wrote them at the top level, where Cursor does not read them.
+4. The plugin registers on `session.created` and, when `context-proxy.env` exists, sends `x-openmem-session-id` through `chat.headers`, so the proxy keys OpenCode trims by the real session id. Neither is verified in a live OpenCode session.
+5. Codex does not guarantee a stable transcript format; unknown rows are skipped.
+6. Cursor Stop retention parses the observed local `agent-transcripts` JSONL shape; live hook `transcript_path` linkage is unverified.
+7. Detects the typed `/smart-compact`, the expanded `<command-name>` tag, and an `openmem:smart-compact` marker; which form Claude Code passes to UserPromptSubmit is unverified.
+8. Verified with `claude -p` on a Claude subscription through LiteLLM v1.106.6: OAuth forwarding, streaming, signed thinking blocks, trims on resumed sessions, compressed tool results, recall injection, prompt-cache reads after a trim. Wiring through `install-coding-agent --context-proxy` (settings.json `env`) is test-covered only.
+9. The `context-proxy` service is pinned to the dev build `ghcr.io/berriai/litellm:v1.109.0-dev.1`, the only LiteLLM release with PR #41522 (ChatGPT-subscription pass-through, `/backend-api/codex/{models,responses}`); v1.106.6 and v1.108.0-rc.1 lack it. Codex keeps its ChatGPT login through a custom `[model_providers.openmem]` (`requires_openai_auth = true`, `base_url = http://127.0.0.1:<port>/backend-api/codex`, the LiteLLM key in `http_headers`); `openai_base_url` alone cannot work, because the pass-through requires `x-litellm-api-key` beside the ChatGPT bearer and Codex 0.162.0 ignores header overrides on the built-in `openai` provider (`merge_configured_model_providers`, `codex-rs/model-provider-info/src/lib.rs`). Verified once live (2026-10-29): Codex 0.162.0 with ChatGPT login, a temp `CODEX_HOME` wired by `installContextProxy`, one `codex exec "reply with OK"` against a throwaway container built from compose.yaml. Codex answered `OK`; the proxy logged `GET /backend-api/codex/models` and `POST /backend-api/codex/responses` (200); the hook stored the turn in `sessions/<codex session id>.db` (`prompt_cache_key` is the session id) and recorded the reported 13,876 prompt tokens. Trims, tool-result compression and recall were not exercised live (one short turn); they ran in the dev image against a fake upstream (`proxy/tests/image/run.py`). Remote compaction is off for a custom provider (`ProviderCapabilities`, `codex-rs/model-provider/src/capabilities.rs`), so Codex compacts locally. Wiring through `install-coding-agent` is test-covered only.
+10. Whether Cursor CLI accepts a custom model base URL is unverified.
+11. The installer sets `provider.anthropic.options.baseURL` and `headers`; whether OpenCode applies `headers` to its built-in Anthropic provider is unverified. Chat Completions and Responses trimming is unit-tested only.
+12. Tested with a fake `rtk` that records its arguments; flags taken from rtk's README and source. No real rtk binary was run.
+13. Tracked upstream in [rtk-ai/rtk#3463](https://github.com/rtk-ai/rtk/issues/3463).
+14. MCP connection checks recorded in `REVAMP.md` (Claude Code, OpenCode; Cursor listed nine tools) ran against the earlier nine-tool list. The current 18 tools add the page, status, initiative and `smart_compact_*` tools, which were checked through the facade only, not listed or called inside any agent.
+15. Checked once live with OpenCode 2.2.1 (`@opencode/cli-linux-x64`, run from a temp directory with temp `HOME`/XDG dirs and `opencode run --standalone`) against a loopback fake OpenAI-compatible model and a fake Hindsight API. Requests reached the fake model with the memory system part, the trimmed messages, the pointer plus recall plus ingest note, and the byte-identical sticky prefix on later turns. A sandbox helper plugin triggered compaction through `ctx.session.compact`; OpenCode stored the plugin's summary as a completed compaction and made no summary model call. Hindsight was a fake server: recall content, retention and the ingest note never touched a real Hindsight. Not checked against a real model provider either. `scripts/tests/test_opencode2_plugin.mjs` and `test_context_trim.mjs` cover the same paths with a fake `ctx`.
+16. OpenCode 2.2.1 loaded the location's plugins after `opencode run` had created the session, so no `session.created` event arrived. The plugin registers on the first `prompt` or `context` hook call instead.
+17. Retention runs from the `experimental.idle` session hook (typed in `@opencode/plugin` 2.2.1; not in the server docs), with `session.execution.succeeded`, `session.status` idle and `session.idle` events as fallbacks. OpenCode 2.2.1 published neither `session.status` nor `session.idle` to the plugin.
+18. Typed `/smart-compact` through `opencode run` arrived as prompt text, and the next request was trimmed. The plugin also registers a `smart-compact` command through `ctx.command.transform`; that path is test-covered only.
+19. OpenCode 2 is never pointed at the context proxy; the plugin trims in its `context` hook ([context proxy](context-proxy.md)). The trim was checked live (footnote 15); tool-result compression is test-covered only, including byte parity with the proxy's `compress_text`.
+20. The installer runs `opencode --version` (major 2 → `"plugins"` directory entry, anything else → `"plugin"` file entry), removes the other shape and skips proxy wiring for OpenCode 2. Tested with a fake `opencode` on `PATH`. The installer itself was not run against a real OpenCode 2 install; the live check configured the plugin directory by hand.
+21. `openmem` mode removes the upstream Hindsight hooks, OpenCode plugin entry, `hindsight` MCP server (only when it runs the upstream `dist/mcp-server.js`) and `hindsight-coding-agent` skill. Locations come from reading `@vectorize-io/hindsight-coding-agents` 0.8.3 `dist/installer.js`; tested against seeded files, not a live upstream install.
+22. At 2c1a245 neither OpenCode plugin emitted a startup banner; banners are being added on this branch and are not yet verified live. For OpenCode 2, per-prompt recall through the prompt hook reached the model live (footnote 15).
+
+Copilot and Pi are not in OpenMem's agent registry. rtk supports both; Pi can point at the context proxy only if it accepts a custom Anthropic base URL (unverified).
+
+## Memory providers
+
+| Capability | Hindsight | mem0 | Cognee |
+| --- | --- | --- | --- |
+| `memory_recall` / `memory_search` | ✅ | 🧪 | 🧪 |
+| `memory_add` | 🧪 | 🧪 | 🧪 |
+| `memory_reflect` | ✅ native `/reflect` | 🧪 search + optional LiteLLM synthesis | 🧪 search + optional LiteLLM synthesis |
+| `memory_consolidate` | 🧪 | ❌ no-op | 🧪 cognify |
+| `memory_pages_list` / `search` / `read` | ✅ | ❌ `supported: false` | ❌ `supported: false` |
+| `memory_capture_initiative` | 🧪 | ❌ `supported: false` | ❌ `supported: false` |
+| `memory_status` (ingest drained, per-operation) | ✅ | 🧪 always ready (synchronous ingest) | ❌ `supported: false` |
+| `smart_compact_search` / `smart_compact_get` | 🧪 local files, provider-independent | 🧪 | 🧪 |
+| Proxy recall injection after a trim | ✅ | ❌ | ❌ |
+| `memory_export` / `memory_import` (PMM) | 🧪 | 🧪 | 🧪 |
+
+"✅" for Hindsight means the call succeeded against the live server on this machine (28 banks, 41,701 facts); `memory_recall` and `memory_reflect` evidence is from `REVAMP.md`, the page and status tools from this branch. mem0 and Cognee rows are covered by facade tests with stubbed HTTP.
+
+## Hindsight model backends (wizard step 3)
+
+| Backend | Status |
+| --- | --- |
+| Ollama in Compose (profile `ollama`) | ✅ retain, reflect and consolidate answered through LiteLLM v1.106.6 |
+| Ollama on the host | 🧪 |
+| lemond on the host | 🧪 |
+| Custom OpenAI-compatible URL | 🧪 |
+| Claude subscription via Meridian | 🧪 stub server only; see [Meridian guide](meridian-litellm.md) |