@bcmyguest/openmem 0.0.0-stage → 0.6.3

package/config/hindsight.env.example

@@ -0,0 +1,24 @@
+# Copy to ~/.config/hindsight/hindsight.env and edit. The real file lives outside the repository;
+# compose.yaml reads it from there (or $HINDSIGHT_ENV_FILE).
+# Docker reaches host services at host.docker.internal.
+# All LLM calls go to the LiteLLM proxy (compose service `litellm`). Models are chosen in config/litellm.*.yaml.
+# scripts/setup.sh --migrate-env writes HINDSIGHT_API_LLM_API_KEY from ~/.config/hindsight/litellm.env.
+HINDSIGHT_API_LLM_PROVIDER=openai
+HINDSIGHT_API_LLM_BASE_URL=http://litellm:4000/v1
+HINDSIGHT_API_LLM_MODEL=memory-reflect
+HINDSIGHT_API_RETAIN_LLM_MODEL=memory-retain
+HINDSIGHT_API_REFLECT_LLM_MODEL=memory-reflect
+HINDSIGHT_API_CONSOLIDATION_LLM_MODEL=memory-consolidate
+HINDSIGHT_API_MENTAL_MODEL_REFRESH_LLM_MODEL=memory-reflect
+HINDSIGHT_API_LLM_API_KEY=replace-me
+HINDSIGHT_API_EMBEDDINGS_PROVIDER=local
+HINDSIGHT_API_RERANKER_PROVIDER=local
+HINDSIGHT_API_WORKER_ID=hindsight-personal
+HINDSIGHT_API_SKIP_LLM_VERIFICATION=true
+HINDSIGHT_API_LLM_MAX_CONCURRENT=1
+HINDSIGHT_API_LLM_TIMEOUT=300
+HINDSIGHT_API_LLM_MAX_RETRIES=1
+
+HINDSIGHT_API_RETAIN_MAX_COMPLETION_TOKENS=16384
+HINDSIGHT_API_REFLECT_MAX_COMPLETION_TOKENS=2048
+HINDSIGHT_API_CONSOLIDATION_MAX_COMPLETION_TOKENS=2048

package/config/index.yml

@@ -0,0 +1,54 @@
+# Project indexer config. The indexer reads the first of: --config PATH, $HINDSIGHT_INDEX_CONFIG,
+# ~/.config/hindsight/index.yml, this file. A per-machine file replaces this one entirely; keys it omits
+# take the built-in values, which match this file. Paths are absolute or start with ~ (a bare ~ is null
+# in YAML, which also means home under roots[].path).
+
+# Git repositories: walk each root to `depth` levels and index the outermost repositories found.
+roots:
+  - path: ~
+    depth: 3
+
+# Extra repositories, indexed even when no root reaches them.
+repos:
+  - ~/.config/nvim
+
+vaults:
+  auto: true     # any folder within a root's depth that contains .obsidian/
+  paths: []      # extra vault folders
+
+# Markdown folders without .obsidian (watched like vaults; banks default to <kind>::<slug>).
+notes:
+  paths: []
+papers:
+  paths: []   # e.g. Zotero Better BibTeX markdown export, arXiv notes, PDF-adjacent .md
+bookmarks:
+  paths: []   # e.g. browser export (Linkwarden, Karakeep, manual markdown dumps)
+
+# Optional: pull RSS/arXiv/OpenAlex into out_dir; indexer watches out_dir as kind `feed`.
+feeds:
+  out_dir: ~/.local/share/personal-memory/feeds
+  rss: []
+  openalex_queries: []
+
+# Glob patterns on absolute paths. A source that matches is skipped.
+exclude: []
+
+# Absolute path prefix -> Hindsight bank id. The longest matching prefix wins; applies to repos and vaults.
+# Unmatched repositories fall back to ~/.config/personal-memory/coding-agent.json mapPathToBank,
+# then the legacy ~/.hindsight/coding-agent.json mapping, then coding-agent::<repository-name>.
+banks:
+  ~/Documents/sample-project: coding-agent::documents-sample-project
+  # ~/Zotero/export-md: papers::zotero
+  # ~/Readwise/Full-Sync: readwise::full-sync
+  # ~/.local/share/personal-memory/feeds: feed::cache
+
+# Largest file indexed, in kilobytes (1 KB = 1000 bytes).
+max_file_kb: 128
+
+# Directory names never descended into (dot-prefixed directories are always skipped).
+skip_dirs: [.cache, .codegraph, .decision, .git, .next, .tasks, .venv, build, dist, node_modules, target, vendor]
+
+# Watcher timings, in seconds. Environment variables POLL_SECONDS, VAULT_QUIET_SECONDS and RELIST_SECONDS override them.
+poll_seconds: 60
+vault_quiet_seconds: 30
+relist_seconds: 600

package/config/litellm.lemond.yaml

@@ -0,0 +1,40 @@
+# LiteLLM routes for Hindsight, backend: lemond on this machine (llama.cpp).
+# Selected by scripts/setup.sh when MEMORY_BACKEND=lemond (the default). See README "Model configuration".
+# Hindsight asks for the fixed aliases below; change the model behind an alias here, not in Hindsight.
+# Every alias runs Nemotron 3.5 Bolt E4B (JSON output and tool calls checked 2026-10-23) with thinking disabled:
+# thinking adds tokens before the answer, and at max_tokens 200 can leave content empty.
+# Passed through to lemond's chat template. Hindsight's per-request reasoning_effort cannot override it.
+model_list:
+  - model_name: memory-retain
+    litellm_params:
+      model: openai/Nemotron-3.5-Bolt-E4B-GGUF
+      api_base: http://host.docker.internal:13305/v1
+      max_tokens: 4096
+      timeout: 300
+      api_key: os.environ/LEMOND_API_KEY
+      extra_body:
+        chat_template_kwargs:
+          enable_thinking: false
+  - model_name: memory-reflect
+    litellm_params:
+      model: openai/Nemotron-3.5-Bolt-E4B-GGUF
+      api_base: http://host.docker.internal:13305/v1
+      max_tokens: 4096
+      timeout: 300
+      api_key: os.environ/LEMOND_API_KEY
+      extra_body:
+        chat_template_kwargs:
+          enable_thinking: false
+  - model_name: memory-consolidate
+    litellm_params:
+      model: openai/Nemotron-3.5-Bolt-E4B-GGUF
+      api_base: http://host.docker.internal:13305/v1
+      max_tokens: 4096
+      timeout: 300
+      api_key: os.environ/LEMOND_API_KEY
+      extra_body:
+        chat_template_kwargs:
+          enable_thinking: false
+
+general_settings:
+  master_key: os.environ/LITELLM_MASTER_KEY

package/config/litellm.ollama.yaml

@@ -0,0 +1,33 @@
+# LiteLLM routes for Hindsight, backend: Ollama on a laptop.
+# Selected by scripts/setup.sh when MEMORY_BACKEND=ollama. See README "Model configuration".
+# Hindsight asks for the fixed aliases below; change the model behind an alias here, not in Hindsight.
+# Every alias disables Gemma thinking: thinking adds tokens before the answer, and at max_tokens 200 can leave content empty.
+# Sent as Ollama's top-level "think": false. Overrides Hindsight's per-request reasoning_effort.
+model_list:
+  - model_name: memory-retain
+    litellm_params:
+      model: ollama_chat/gemma4:e2b
+      api_base: http://host.docker.internal:11434
+      max_tokens: 4096
+      timeout: 300
+      extra_body:
+        think: false
+  - model_name: memory-reflect
+    litellm_params:
+      model: ollama_chat/gemma4:e4b
+      api_base: http://host.docker.internal:11434
+      max_tokens: 4096
+      timeout: 300
+      extra_body:
+        think: false
+  - model_name: memory-consolidate
+    litellm_params:
+      model: ollama_chat/gemma4:e2b
+      api_base: http://host.docker.internal:11434
+      max_tokens: 4096
+      timeout: 300
+      extra_body:
+        think: false
+
+general_settings:
+  master_key: os.environ/LITELLM_MASTER_KEY

package/config/notebooklm.yml

@@ -0,0 +1,33 @@
+# NotebookLM sync (opt-in: docker compose --profile notebooklm up -d notebooklm).
+# Per-machine override: ~/.config/hindsight/notebooklm.yml. Put only the keys you change there;
+# mappings merge key by key, lists and scalars replace the shipped value.
+
+enabled: false
+
+# client: unofficial notebooklm-py client, uses the browser login stored in ~/.config/notebooklm.
+# enterprise: documented NotebookLM Enterprise REST API (notebook list only; see README).
+backend: client
+
+interval_minutes: 60
+
+# Hindsight bank per notebook: <bank_prefix>::<slug of notebook title>.
+bank_prefix: notebooklm
+
+# Title globs (fnmatch, case-insensitive). include empty means every notebook.
+include_notebooks: []
+exclude_notebooks: []
+
+include:
+  notes: true
+  sources: true   # source list, URLs, full text and guide summary where the client returns them
+  chats: false    # saved chat question/answer history
+
+client:
+  # Empty uses NOTEBOOKLM_HOME (set to /data/notebooklm in the container).
+  storage_path: ""
+
+enterprise:
+  project_number: ""          # numeric project number, required for backend: enterprise
+  location: global            # global | us | eu
+  service_account_file: ""    # path inside the container; empty uses Application Default Credentials
+  notebook_limit: 500         # listRecentlyViewed page size, 1..500

package/config/openmem.toml.example

@@ -0,0 +1,62 @@
+# Mise-like declarative config for the openmem meta wizard.
+#
+#   mkdir -p ~/.config/personal-memory
+#   cp config/openmem.toml.example ~/.config/personal-memory/config.toml
+#   $EDITOR ~/.config/personal-memory/config.toml
+#   ./setup --yes
+#
+# Precedence (highest wins): CLI flags → environment variables →
+#   ~/.config/personal-memory/config.toml → ./personal-memory.toml (stack root) →
+#   ~/.config/hindsight/wizard.conf (last configure run).
+#
+# Provider-native settings (mem0 cloud, Hindsight product UI, etc.) stay in those tools;
+# this file only describes how this machine runs the shared stack.
+
+[memory]
+provider = "hindsight"
+
+[stack]
+project = "openmem"
+api_port = 8888
+control_plane_port = 9999
+
+# Default wizard action when ./setup runs non-interactively without --up/--down
+[wizard]
+action = "configure" # configure | up | down
+
+# LLM routing for Hindsight (LiteLLM → lemond/Ollama/custom). Not lemond's own config.
+[model]
+backend = "lemond" # lemond | ollama | custom
+retain = "Gemma-4-E2B-it-GGUF"
+reflect = ""       # empty = shipped memory-reflect route
+api_base = ""      # custom backend only
+
+[model.lemond]
+host = "http://127.0.0.1:13305"
+
+[model.ollama]
+host = "http://127.0.0.1:11434"
+
+# Optional indexer defaults (wizard may still prompt interactively)
+# [[index.roots]]
+# path = "~"
+# depth = 3
+
+# Mise-style named tasks (run via ./pm <name>)
+[tasks.configure]
+description = "Secrets, index sources, build images, compose up"
+
+[tasks.up]
+description = "Start stack using existing config"
+
+[tasks.down]
+description = "docker compose down for this project"
+
+[tasks.doctor]
+description = "Validate memory setup on this machine"
+
+# Provider-native options live in their own tables, not under [model].
+# mem0 is URL-only: point at a self-hosted REST server (not https://api.mem0.ai).
+# [memory.mem0]
+# api_url = "http://127.0.0.1:18888"
+# env_file = "~/.config/personal-memory/mem0.env"

package/docs/OPENMEM.md

@@ -0,0 +1,23 @@
+# OpenMem
+
+**OpenMem** is the product name for this repository (formerly *personal-memory*).
+
+For the product idea — memory interface for coding agents, providers, `memory_*`, banks, formats — start with **[Concepts](https://bcmyguest.github.io/openmem/docs/concepts/)**.
+
+## CLI
+
+```sh
+npx @bcmyguest/openmem
+openmem setup
+openmem doctor
+```
+
+Bins: `openmem`, `openmem-setup`, `openmem-mcp`, `openmem-install-mcp`, `openmem-install-coding-agent`, `openmem-switch-provider`, `openmem-notebooklm-mcp`, `openmem-cognee-mcp`.
+
+Machine config paths under `~/.config/personal-memory/` and `~/.config/hindsight/` stay as-is for now so existing installs keep working. Installers rewrite leftover `personal-memory` MCP server entries to `openmem`.
+
+## Repo
+
+- GitHub: [bcmyguest/openmem](https://github.com/bcmyguest/openmem)
+- Docs: [site](https://bcmyguest.github.io/openmem/) · [Concepts](https://bcmyguest.github.io/openmem/docs/concepts/) · [Quickstart](https://bcmyguest.github.io/openmem/docs/getting-started/)
+- npm: `openmem` (package formerly `personal-memory`)

package/docs/architecture.md

@@ -0,0 +1,219 @@
+# Architecture
+
+openmem’s job is **not** to be the memory — it is to let you run **whichever memory system you choose** on one machine with shared indexing and setup. A **shared indexer** writes into the active **provider**; **coding agents** reach that API through unified `memory_*` MCP, in-repo **session hooks**, and optional native paths (Hindsight plugin, mem0/Cognee MCP). Only one provider is active at a time; `npx @bcmyguest/openmem switch` rewires the stack without pretending to migrate your data. Setup (`npx @bcmyguest/openmem`) is install plumbing only — not part of the runtime data path.
+
+## 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(optional --hindsight-plugin)"]
+    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 is a **meta layer**: it does not replace provider APIs. It wires the same plumbing (indexer, compose, wizard, MCP) to **different backends** through manifests and thin adapters.
+
+```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 + optional plugin/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 backend (`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_*` | `install-coding-agent --yes` |
+| **Hindsight (optional)** | `@vectorize-io/hindsight-coding-agents` plugin | `install-coding-agent --hindsight-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) |
+
+**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) with `--hindsight-plugin` adds a second hook set on Hindsight stacks.
+
+### 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 | `--hindsight-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,51 @@
+# 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](../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`).
+- **Optional:** `--hindsight-plugin` with `MEMORY_PROVIDER=hindsight` also runs `@vectorize-io/hindsight-coding-agents install` (legacy/alternate hook set).
+
+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.
+
+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.
+
+## 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,51 @@
+# Coding agents and MCP
+
+One entry point for session wiring on **every** provider (unified MCP + in-repo session hooks):
+
+```sh
+npx @bcmyguest/openmem install-coding-agent --yes
+# optional: --hindsight-plugin (also run @vectorize-io/hindsight-coding-agents on Hindsight stacks)
+# same flags: --dry-run, --agents claude-code,codex,opencode,cursor-cli,hermes,gemini-cli,amp,cline
+```
+
+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](../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 enables `features.hooks` when unset and preserves an explicit `false`. 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. It does not remove the optional Hindsight plugin; after checking the new MCP and hooks, remove the old plugin through its own uninstaller if you no longer want both integrations running.
+
+The wizard coding-agent step follows the same idea for Hindsight-first flows.
+
+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: npx . 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: npx . 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`.