better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/pi-and-omp/omp/mcp.md

@@ -0,0 +1,260 @@
+<!--
+source: https://omp.sh/docs/mcp
+fetched: 2026-09-06
+-->
+
+# MCP
+
+> Connect omp to external services and local programs through Model Context Protocol servers.
+
+## Connect your first server
+
+Use MCP when a service or tool already publishes an MCP server and you want omp to work with it—for example, to search an issue tracker, query a database, or use a filesystem outside the current project. You configure the server once, then ask for the work in ordinary language.
+
+The quickest route is the guided setup inside omp:
+
+```text
+/mcp add
+```
+
+Choose **Project** when everyone working in this repository should discover the server, or **User** when it is only for you. After setup, verify it immediately:
+
+```text
+/mcp test filesystem
+```
+
+A successful test shows the server name and version, its tool count, and up to ten tool names. You can then ask, for example:
+
+> Use the filesystem MCP server to summarize the Markdown files in my Documents folder.
+
+You do not need to address MCP tools by their internal names.
+
+## Minimal configuration
+
+For a local server, create `.omp/mcp.json` in the project. This example starts the official filesystem server and grants it access only to one directory:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json",
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-filesystem",
+        "/Users/alice/Documents"
+      ]
+    }
+  }
+}
+```
+
+Replace the path with an absolute directory on your machine. `stdio` is the default transport when `type` is omitted.
+
+If you edit the file while omp is running, apply and verify the change with:
+
+```text
+/mcp reload
+/mcp list
+/mcp test filesystem
+```
+
+`/mcp list` groups servers by source and shows whether each one is connected, connecting, inactive, disabled, or not connected.
+
+## Where omp looks
+
+You often do not need to copy an existing MCP setup. omp automatically imports supported server definitions from Claude Code, Codex, Gemini CLI, OpenCode, Cursor, Windsurf, VS Code, installed plugins, and extension packages. Run `/mcp list` to see what was found and which file supplied it.
+
+For configuration owned by omp, prefer:
+
+| Scope | File | Use it for |
+| --- | --- | --- |
+| Project | `.omp/mcp.json` | A server definition shared by this repository |
+| User | `~/.omp/agent/mcp.json` | Your personal servers in the default profile |
+| Named profile | `~/.omp/profiles/<name>/agent/mcp.json` | Servers isolated to `omp --profile <name>` |
+| Portable fallback | `mcp.json` or `.mcp.json` at the project root | A lowest-priority file shared with other MCP clients |
+
+Project MCP discovery is enabled by default. The first definition found for a duplicate server wins; definitions are not merged. `/mcp add`, `/mcp enable`, `/mcp disable`, and OAuth commands write only omp-managed files, not another application's config.
+
+## Transports
+
+Choose the transport published by the server. A URL ending in `/sse` does not by itself select SSE; set `type` explicitly for every remote server.
+
+| Transport | Required fields | When to use it |
+| --- | --- | --- |
+| `stdio` | `command`; optional `args`, `env`, `cwd` | A local executable. `type` may be omitted. |
+| `http` | `type: "http"`, `url`; optional `headers` | A hosted Streamable HTTP server. Use this for new remote integrations. |
+| `sse` | `type: "sse"`, `url`; optional `headers` | A legacy HTTP+SSE server that specifically requires the older transport. |
+
+A minimal Streamable HTTP entry looks like this:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json",
+  "mcpServers": {
+    "acme": {
+      "type": "http",
+      "url": "https://mcp.example.com/mcp"
+    }
+  }
+}
+```
+
+A server cannot have both `command` and `url`.
+
+## Authentication and secrets
+
+### Bearer tokens and API keys
+
+Put credentials for a local process in `env`, or credentials for HTTP/SSE in `headers`. Reference an environment variable instead of committing the secret:
+
+```json
+{
+  "mcpServers": {
+    "acme": {
+      "type": "http",
+      "url": "https://mcp.example.com/mcp",
+      "headers": {
+        "Authorization": "Bearer ${ACME_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+omp expands `${VAR}` and `${VAR:-default}` in server configuration when it loads the file. In `env` and `headers`, a whole value that names an environment variable also resolves from the process environment. A value beginning with `!` runs the remaining shell command and uses its trimmed output; use that only with a command you trust.
+
+Although `auth.type: "apikey"` is accepted by the schema, it does not fetch and inject an API key. Use `env` or `headers` for API keys.
+
+### OAuth
+
+For an HTTP or SSE server that supports OAuth, leave the token out and run:
+
+```text
+/mcp reauth acme
+```
+
+omp opens the authorization flow and stores the credential in the active profile's auth storage (`agent.db`, or the configured auth broker), not in `mcp.json`. Use `/mcp unauth acme` to remove it. If the provider requires a registered client, add only the settings it requires:
+
+```json
+{
+  "mcpServers": {
+    "acme": {
+      "type": "http",
+      "url": "https://mcp.example.com/mcp",
+      "oauth": {
+        "clientId": "${ACME_CLIENT_ID}",
+        "clientSecret": "${ACME_CLIENT_SECRET}"
+      }
+    }
+  }
+}
+```
+
+OAuth credentials are bound to the active profile and server URL. The same profile may reuse that credential for the same URL in another checkout. An explicit `Authorization` header takes precedence over managed OAuth, so remove a stale header before reauthorizing.
+
+## Inspect and control servers
+
+| Command | What you see or change |
+| --- | --- |
+| `/mcp list` | Configured and discovered servers, source files, transports, and connection states |
+| `/mcp test <name>` | A temporary connection test, server version, tool count, and up to ten upstream tool names; press Esc to cancel |
+| `/mcp reload` | Rediscover config files and rebuild the current session's MCP connections and tools |
+| `/mcp reconnect <name>` | Reconnect one known server without rediscovering every config file |
+| `/mcp enable <name>` | Enable a server; for imported config, create a user-level override |
+| `/mcp disable <name>` | Disable a server by name, including one imported from another tool |
+| `/mcp reauth <name>` | Replace the active profile's managed OAuth credential |
+| `/mcp unauth <name>` | Remove that managed OAuth credential |
+| `/mcp resources` | List resources and resource templates exposed by connected servers |
+| `/mcp prompts` | List prompts exposed by connected servers and their slash-command names |
+| `/mcp notifications` | Show notification support, subscriptions, and whether update injection is enabled |
+| `/mcp remove <name> [--scope project\|user]` | Delete an omp-managed definition; project is the default scope |
+| `/mcp help` | Show the current command reference |
+
+`/tools` shows every tool currently visible to omp. MCP tool names appear as `mcp__<server>_<tool>` after names are lowercased and normalized to underscores. omp may remove a repeated server prefix or shorten a very long name. These names help you identify where a capability came from; continue requesting work in natural language.
+
+Connected servers may also publish prompts, resources, and notifications. `/mcp prompts` shows callable prompt commands in the form `/server:prompt`. Resource updates enter the conversation only when `mcp.notifications` is enabled; the default is off.
+
+## Safety
+
+Treat every MCP definition as executable, trusted configuration:
+
+- A `stdio` server runs its configured command with your user permissions. Review project MCP files before opening an unfamiliar repository.
+- Grant the smallest useful filesystem roots, OAuth scopes, database permissions, and API permissions.
+- A remote server receives the arguments and data needed for each requested operation. Use only endpoints and server packages you trust.
+- Never commit tokens or client secrets. Prefer environment variables, a trusted secret command, or managed OAuth.
+- Because OAuth is profile-scoped by URL, an untrusted checkout defining the same URL can use that profile's stored credential. Use a separate profile for untrusted projects.
+- Disable an unwanted discovered server with `/mcp disable <name>` rather than editing another application's config.
+
+## Troubleshooting
+
+### The server is missing from `/mcp list`
+
+Check that the JSON parses and contains a top-level `mcpServers` object, then run `/mcp reload`. A user-level `disabledServers` entry may hide the server. Project sources are also skipped when `mcp.enableProjectConfig` is false. If the name exists in several sources, the higher-priority definition wins.
+
+### A remote server says `stdio server requires "command"`
+
+Add `"type": "http"` (or `"sse"` for a legacy server). Without `type`, omp assumes `stdio`.
+
+### A local server will not connect
+
+Run `/mcp test <name>` and check that the executable is installed, `cwd` exists, arguments are correct, and required environment variables are available to the process that launched omp. A stdio server must reserve stdout for MCP protocol messages; send diagnostic logs to stderr.
+
+### The server returns 401 or 403
+
+For managed OAuth, run `/mcp reauth <name>`. If needed, use `/mcp unauth <name>` first. For header authentication, confirm the environment variable is set and remove any stale explicit `Authorization` header that would override OAuth.
+
+### The connection times out
+
+Set a larger per-server `timeout` in milliseconds, then reload. The default is 30 seconds; `0` disables client-side MCP timeouts. `OMP_MCP_TIMEOUT_MS` overrides every per-server timeout for the process.
+
+```json
+{
+  "mcpServers": {
+    "slow-server": {
+      "type": "http",
+      "url": "https://mcp.example.com/mcp",
+      "timeout": 120000
+    }
+  }
+}
+```
+
+Use `/mcp reconnect <name>` for a transient failure. Use `/mcp reload` after changing files or when discovery itself is wrong.
+
+## Server field reference
+
+| Field | Applies to | Meaning |
+| --- | --- | --- |
+| `enabled` | All | Connect unless `false`; user enable/disable overrides can supersede imported definitions |
+| `timeout` | All | Request timeout in milliseconds; `0` disables it |
+| `requestIdFormat` | All | `"number"` by default; use `"string"` only for a server that requires string JSON-RPC IDs |
+| `command` | stdio | Executable to start |
+| `args` | stdio | Argument array passed without shell parsing |
+| `env` | stdio | Environment variables passed to the process |
+| `cwd` | stdio | Working directory for the process |
+| `url` | http, sse | Remote MCP endpoint |
+| `headers` | http, sse | Request headers, including token authentication |
+| `oauth` | http, sse | Optional `clientId`, `clientSecret`, `redirectUri`, `callbackPort`, `callbackPath`, and `prompt` settings for authorization |
+| `auth` | All | Advanced stored-credential metadata; normally generated/resolved by managed OAuth rather than written by hand |
+
+User config may also contain `disabledServers` and `enabledServers` arrays. The denylist has highest precedence.
+
+These related settings live in `~/.omp/agent/config.yml` (or the active profile's config):
+
+```yaml
+mcp:
+  enableProjectConfig: true
+  renderMarkdownResults: true
+  notifications: false
+  notificationDebounceMs: 500
+```
+
+Those are the defaults. `notificationDebounceMs` controls how long resource updates are grouped before they enter the conversation.
+
+## Related
+
+- [Custom tools](/docs/custom-tools) — write a small native tool when no suitable MCP server exists.
+- [MCP server authoring](/docs/mcp-authoring) — build and package a server of your own.
+- [Settings](/docs/settings) — configure project discovery, notifications, and result rendering.
+- [Plugins](/docs/plugins) — distribute MCP definitions with other omp extensions.

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/pi-and-omp/omp/memory.md

@@ -0,0 +1,306 @@
+<!--
+source: https://omp.sh/docs/memory
+fetched: 2026-09-06
+-->
+
+# Memory
+
+> Carry durable preferences, decisions, and project knowledge into later sessions. Memory is off by default; choose a local or remote backend, control its scope, and inspect or clear what it contributes.
+
+Memory helps omp continue work without making you restate durable facts such as repository conventions, architectural decisions, and review preferences. It is separate from [compaction](/docs/compaction): compaction shortens one session, while memory can affect future sessions.
+
+Memory is **off by default**. If you want it, open `/settings`, select the **Memory** tab, and choose one backend. Start with `mnemopi` for searchable memory stored on this machine, `local` for automatic project summaries, or `hindsight` when you already operate a Hindsight service.
+
+## Choose a backend
+
+| Backend | Use it when | Storage and default scope | Important trade-off |
+| --- | --- | --- | --- |
+| `off` (default) | You do not want cross-session knowledge. | No memory store. | Existing session transcripts are unaffected; turning memory off does not delete them. |
+| `local` | You want omp to periodically distill past persisted sessions into project guidance. | Generated files on this machine, isolated by working directory. | It is a batch summary pipeline, not a searchable store. You cannot review or forget one structured fact. |
+| `mnemopi` | You want prompt-driven remember, recall, and forget behavior without a memory server. | Local SQLite databases; `per-project` by default. | The database is local, but the default `smol` LLM mode can send extraction work to your configured model provider. |
+| `hindsight` | You want a remote bank, shared infrastructure, or Hindsight's synthesis and mental models. | Your Hindsight server; `per-project-tagged` by default. | Automatic retention is on by default, so conversation text leaves the machine. |
+
+The smallest persistent setup from a shell is:
+
+```bash
+# Pick exactly one
+omp config set memory.backend local
+omp config set memory.backend mnemopi
+omp config set memory.backend hindsight
+
+# Confirm the effective setting
+omp config get memory.backend
+```
+
+`/settings` writes the global config and switches the active backend when you save it. Shell or YAML changes apply to new omp processes. For one repository only, put the same keys in `<repo>/.omp/config.yml`; project settings override the global file. See [Settings](/docs/settings) for paths and precedence.
+
+## Privacy, scope, and defaults
+
+Enabling memory changes what persists and, depending on the backend, what may cross a network boundary.
+
+- **Off means no memory processing.** It does not disable ordinary session persistence. Memory commands also do not erase files under `~/.omp/agent/sessions/`; manage those separately through [Sessions](/docs/sessions).
+- **Local stores generated artifacts locally**, under `~/.omp/agent/memories/<encoded-project>/` by default. Its extraction and consolidation passes use your configured model roles, so past session text can still be sent to that model provider. Generated outputs are filtered for common token and secret patterns, but do not intentionally ask omp to remember secrets.
+- **Mnemopi stores its SQLite banks locally**, under `~/.omp/agent/memories/mnemopi/` by default. Local embeddings may download and run an embedding model. Its default `llmMode: smol` uses your configured online `tiny`/`smol` model for LLM-backed extraction; use `llmMode: none` when you want no LLM-backed memory processing.
+- **Hindsight stores durable memory on the configured server.** With `autoRetain: true` (the default), omp sends user and assistant text every three user turns and at session boundaries. It omits tool calls, tool results, and thinking blocks. Recall and synthesis queries also go to that server.
+- **Turning a backend off does not delete its store.** This makes switching reversible, but you must clear or delete data separately when removal is the goal.
+
+Choose scope before accumulating sensitive data:
+
+| Scope | Mnemopi | Hindsight |
+| --- | --- | --- |
+| `global` | One local bank is visible in every project. | One remote bank is visible in every project. |
+| `per-project` | One isolated bank derived from the absolute working directory. This is the default. | One isolated bank per repository name (or cwd name outside Git). Linked worktrees of one repository share the primary checkout's name. |
+| `per-project-tagged` | Writes to the project bank; recall combines it with the shared global bank. | Writes project-tagged data to one shared bank; recall combines that project's tagged memories with untagged global memories. This is the default. |
+
+For client work or other hard boundaries, prefer `per-project`. `per-project-tagged` is convenient, but intentionally makes untagged global knowledge visible alongside project knowledge.
+
+## Use memory in conversation
+
+With Mnemopi or Hindsight enabled, use ordinary prompts. You do not need to know how omp performs the memory operation.
+
+```text
+Remember that this repository uses pnpm and Node 22.
+```
+
+```text
+Before changing authentication, recall why we rejected session cookies.
+```
+
+```text
+What durable preferences have you learned about how I review pull requests?
+```
+
+Mnemopi can also edit, forget, or invalidate an editable memory:
+
+```text
+Forget the memory that says releases happen on Fridays; that policy was retired.
+```
+
+```text
+Update the stored release convention to say that releases happen after CI is green.
+```
+
+Ask omp to show the candidate memory before changing it when the description could match more than one entry. Mnemopi's extracted fact-table rows are read-only; the prompt should identify an editable memory, or you can clear the scoped bank when complete removal is required. Hindsight does not expose individual record editing through omp; use the Hindsight service's UI for record-level review or deletion.
+
+The local backend works differently. It automatically summarizes eligible persisted sessions and injects a static **Memory Guidance** block at startup. A request such as “remember this” is not a guaranteed individual write. Its best use is allowing recurring project knowledge to emerge from completed work.
+
+Recalled or summarized memory is background context, not an instruction. Current prompts and current repository state take precedence when they conflict with it.
+
+## What you can inspect and control
+
+Run these slash commands in a session:
+
+| Command | Visible result |
+| --- | --- |
+| `/memory` or `/memory view` | Opens the current memory injection payload. An empty warning means the backend is off, unavailable, or has not recalled/generated anything yet. |
+| `/memory stats` | Shows backend statistics when the active backend supports them. |
+| `/memory diagnose` | Shows backend-specific diagnostics when supported. |
+| `/memory enqueue` | Requests the active backend's stronger maintenance/retention action; details differ by backend below. |
+| `/memory clear` | Clears what the active backend can clear. Hindsight is an important exception: the remote bank is not deleted. |
+
+`/memory reset` is an alias for `clear`; `/memory rebuild` is an alias for `enqueue`.
+
+### What enqueue and clear mean
+
+| Backend | `/memory enqueue` | `/memory clear` |
+| --- | --- | --- |
+| Local | Marks consolidation work for the next startup. It does not rebuild the guidance panel immediately. | Removes this project's generated artifacts and resets the local pipeline's shared extraction/consolidation index. It does not delete session transcripts. |
+| Mnemopi | Forces current-session retention, drains pending extraction, and consolidates eligible working memories. Fresh rows are not promoted until they pass Mnemopi's age gate (12 hours with the default 24-hour working-memory lifetime). | Deletes the SQLite databases and WAL/SHM sidecars for the active scope, then starts an empty backend again. |
+| Hindsight | Flushes queued writes and forces retention of the current session. | Flushes pending writes, then clears the local recall state for this session only. It does **not** delete server-side memories or the bank; use the Hindsight UI to do that. |
+
+### Review local generated files
+
+The local backend keeps readable generated artifacts below `~/.omp/agent/memories/<encoded-project>/`:
+
+- `memory_summary.md` — compact guidance shown by `/memory view` and injected at startup
+- `MEMORY.md` — the longer consolidated project memory
+- `learned.md` — explicitly captured lessons when optional auto-learn is enabled
+- `skills/` — generated procedural playbooks
+
+These are generated files, not the source session history. Editing them is not a durable workflow because later consolidation can replace them. Clear stale output and enqueue a rebuild instead.
+
+### Manage Hindsight mental models
+
+Hindsight mental models are curated summaries such as user preferences, project conventions, and project decisions. They are enabled and automatically seeded by default. In the interactive TUI, use:
+
+| Command | Effect |
+| --- | --- |
+| `/memory mm list` | List models in the active bank. |
+| `/memory mm show <id>` | Show one model. |
+| `/memory mm refresh [id]` | Refresh one model, or all auto-refresh models when no id is supplied. |
+| `/memory mm history <id>` | Show that model's revision history as a diff. |
+| `/memory mm seed` | Create any missing built-in models. |
+| `/memory mm delete <id>` | Delete one mental model. This does not delete its source memories. |
+| `/memory mm reload` | Reload the mental-model block used by the current session. |
+
+Mental-model commands are TUI-only and require an active Hindsight backend. They are not Mnemopi controls.
+
+## Configure the local backend
+
+Minimal global YAML in `~/.omp/agent/config.yml`:
+
+```yaml
+memory:
+  backend: local
+```
+
+The pipeline starts in the background when omp starts. It skips subagents and sessions that were not persisted. By default, it ignores sessions still active within the last 12 hours and sessions older than 30 days, so a newly enabled backend may initially show an empty payload. Per-session extraction uses the `default` model role; consolidation uses `smol` with fallbacks.
+
+| Setting | Default | Purpose |
+| --- | --- | --- |
+| `memories.maxRolloutAgeDays` | `30` | Ignore sessions older than this. |
+| `memories.minRolloutIdleHours` | `12` | Ignore sessions active more recently than this. |
+| `memories.maxRolloutsPerStartup` | `64` | Maximum sessions processed at one startup. |
+| `memories.threadScanLimit` | `300` | Maximum recent session records scanned. |
+| `memories.maxRawMemoriesForGlobal` | `200` | Maximum extracted session memories passed to consolidation. |
+| `memories.stage1Concurrency` | `8` | Concurrent per-session extraction jobs. |
+| `memories.stage1LeaseSeconds` | `120` | Extraction job lease. |
+| `memories.stage1RetryDelaySeconds` | `120` | Delay before retrying failed extraction. |
+| `memories.phase2LeaseSeconds` | `180` | Consolidation job lease. |
+| `memories.phase2RetryDelaySeconds` | `180` | Delay before retrying failed consolidation. |
+| `memories.phase2HeartbeatSeconds` | `30` | Consolidation lease heartbeat. |
+| `memories.rolloutPayloadPercent` | `0.7` | Fraction of the model context budget available to session payloads. |
+| `memories.phase1InputTokenLimit` | `4000` | Per-session extraction input cap. |
+| `memories.fallbackTokenLimit` | `16000` | Fallback budget when a model has no finite declared context window. |
+| `memories.summaryInjectionTokenLimit` | `5000` | Shared approximate cap for summary and captured lessons injected at startup. |
+
+Optional `autolearn.enabled: true` lets omp capture explicit lessons into `learned.md`; it is experimental and off by default. `autolearn.autoContinue` is also false by default and controls whether omp runs a private capture turn after stopping.
+
+## Configure Mnemopi
+
+The defaults are enough for a project-isolated local bank:
+
+```yaml
+memory:
+  backend: mnemopi
+```
+
+A privacy-oriented FTS-only setup that avoids LLM-backed extraction is:
+
+```yaml
+memory:
+  backend: mnemopi
+mnemopi:
+  scoping: per-project
+  noEmbeddings: true
+  llmMode: none
+```
+
+### Storage, scope, and automation
+
+| Setting | Default | Purpose |
+| --- | --- | --- |
+| `mnemopi.dbPath` | Agent memories directory | Optional SQLite path. |
+| `mnemopi.bank` | Unset (`default`) | Shared bank base name; project scopes derive a project bank from it. |
+| `mnemopi.scoping` | `per-project` | `global`, `per-project`, or `per-project-tagged`. |
+| `mnemopi.autoRecall` | `true` | Recall into the first turn of a session. |
+| `mnemopi.autoRetain` | `true` | Retain completed conversation turns automatically. |
+| `mnemopi.retainEveryNTurns` | `4` | Minimum user turns between automatic writes. |
+| `mnemopi.recallLimit` | `8` | Maximum memories included in recalled context. |
+| `mnemopi.recallContextTurns` | `3` | Prior user-bounded turns included in a recall query. |
+| `mnemopi.recallMaxQueryChars` | `4000` | Maximum composed recall query length. |
+| `mnemopi.injectionTokenLimit` | `5000` | Approximate memory context budget. |
+
+### Retrieval, embeddings, and LLM processing
+
+| Setting | Default | Purpose |
+| --- | --- | --- |
+| `mnemopi.polyphonicRecall` | `false` | Combine vector, graph, fact, and temporal recall. |
+| `mnemopi.enhancedRecall` | `false` | Cache repeated and similar recall queries. |
+| `mnemopi.proactiveLinking` | `false` | Link new memories to related graph entities and memories. |
+| `mnemopi.noEmbeddings` | `false` | Use deterministic full-text search only. |
+| `mnemopi.embeddingVariant` | `en` | Local model family: `en` or `multilingual`. Changing it rebuilds embeddings on the next writable start. |
+| `mnemopi.embeddingModel` | Variant default | Explicit embedding model id; overrides the variant. |
+| `mnemopi.embeddingApiUrl` | Environment/default | Optional OpenAI-compatible embedding endpoint. |
+| `mnemopi.embeddingApiKey` | Environment/default | Credential for that embedding endpoint. |
+| `mnemopi.llmMode` | `smol` | `smol` uses the configured `tiny`/`smol` role, `remote` uses the endpoint below, and `none` disables LLM calls. |
+| `mnemopi.llmBaseUrl` | Environment/default | OpenAI-compatible LLM endpoint for `remote` mode. |
+| `mnemopi.llmApiKey` | Environment/default | Credential for the remote LLM. |
+| `mnemopi.llmModel` | Environment/default | Remote LLM model id. |
+| `mnemopi.debug` | `false` | Enable backend debug logging. |
+
+## Configure Hindsight
+
+Run a reachable [Hindsight](https://hindsight.vectorize.io/) server first. The built-in URL is `http://localhost:8888`, so a local unauthenticated server needs only:
+
+```yaml
+memory:
+  backend: hindsight
+```
+
+For Hindsight Cloud or an authenticated deployment:
+
+```yaml
+memory:
+  backend: hindsight
+hindsight:
+  apiUrl: https://api.hindsight.vectorize.io
+  scoping: per-project
+```
+
+Keep the token outside the file when possible:
+
+```bash
+export HINDSIGHT_API_TOKEN='replace-me'
+omp
+```
+
+`HINDSIGHT_*` environment variables override matching `hindsight.*` settings. See [Environment variables](/docs/env) for the override names and parsing rules.
+
+### Connection, banks, and retention
+
+| Setting | Default | Purpose |
+| --- | --- | --- |
+| `hindsight.apiUrl` | `http://localhost:8888` | Cloud or self-hosted server URL. |
+| `hindsight.apiToken` | Unset | Bearer token for authenticated servers. |
+| `hindsight.bankId` | `omp` | Base bank id. In `per-project` mode the project name is appended. |
+| `hindsight.bankIdPrefix` | Unset | Optional prefix added before the base bank id. |
+| `hindsight.scoping` | `per-project-tagged` | `global`, `per-project`, or `per-project-tagged`. |
+| `hindsight.bankMission` | Unset | Optional mission applied when omp creates the bank. |
+| `hindsight.retainMission` | Unset | Optional instruction for retention. |
+| `hindsight.autoRecall` | `true` | Recall before the first model turn. |
+| `hindsight.autoRetain` | `true` | Retain transcript text on cadence and at session boundaries. Set false for prompt-driven writes only. |
+| `hindsight.retainMode` | `full-session` | `full-session` upserts one session document; `last-turn` stores turn-bounded chunks. |
+| `hindsight.retainEveryNTurns` | `3` | User turns between automatic retention. |
+| `hindsight.retainOverlapTurns` | `2` | Overlap between retained chunks in `last-turn` mode. |
+| `hindsight.retainContext` | `omp` | Context label sent with retained data. |
+
+### Recall, mental models, and timeouts
+
+| Setting | Default | Purpose |
+| --- | --- | --- |
+| `hindsight.recallBudget` | `mid` | Recall effort: `low`, `mid`, or `high`. |
+| `hindsight.recallMaxTokens` | `1024` | Maximum recalled tokens. |
+| `hindsight.recallContextTurns` | `1` | Prior user-bounded turns included in recall queries. |
+| `hindsight.recallMaxQueryChars` | `800` | Maximum recall query length. |
+| `hindsight.recallTypes` | `["world", "experience"]` | Hindsight memory types eligible for recall. |
+| `hindsight.mentalModelsEnabled` | `true` | Load curated mental models into new sessions. |
+| `hindsight.mentalModelAutoSeed` | `true` | Create missing built-in user-preference, project-convention, and project-decision models at startup. |
+| `hindsight.mentalModelRefreshIntervalMs` | `300000` | Refresh interval for eligible mental models. |
+| `hindsight.mentalModelMaxRenderChars` | `16000` | Maximum rendered mental-model text. |
+| `hindsight.requestTimeoutMs` | `30000` | Default request deadline. |
+| `hindsight.recallTimeoutMs` | `30000` | Recall deadline. |
+| `hindsight.retainTimeoutMs` | `60000` | Retention deadline. |
+| `hindsight.reflectTimeoutMs` | `120000` | Synthesis deadline. |
+| `hindsight.debug` | `false` | Enable request and backend debug logging. |
+
+## Troubleshooting
+
+**`/memory view` is empty after enabling local memory.** Local memory only processes persisted primary sessions, skips sessions active within the last 12 hours by default, and performs maintenance at startup. Run `/memory enqueue`, exit normally, and start omp again after eligible sessions exist. Also make sure the `default` and `smol` model roles have usable credentials.
+
+**Mnemopi is enabled but does not remember or recall.** Run `/memory diagnose` and `/memory stats`. Startup is best-effort: a database, embedding-model, or LLM initialization failure leaves the coding session usable but memory inert. Try `mnemopi.noEmbeddings: true` to isolate embedding problems, and use `mnemopi.llmMode: none` to isolate LLM configuration.
+
+**Hindsight is enabled but nothing appears.** Confirm the effective backend and endpoint:
+
+```bash
+omp config get memory.backend
+omp config get hindsight.apiUrl
+```
+
+Then run `/memory diagnose`. Check that the server is reachable and that `HINDSIGHT_API_TOKEN` or `hindsight.apiToken` is valid. Request failures do not stop the coding session; enable `hindsight.debug` when you need backend logs.
+
+**One project sees knowledge from another.** Check `mnemopi.scoping` or `hindsight.scoping`. Switch to `per-project` for isolation, then clear the old local banks or remove the old Hindsight bank/data separately; changing scope does not erase previously stored knowledge.
+
+**Memory is stale.** Ask omp to verify it against the current repository. For one Mnemopi fact, ask to update or forget it. For local summaries, use `/memory clear` followed by `/memory enqueue` and a later restart. For Hindsight, remove or correct the remote record in Hindsight; `/memory clear` only clears the current session's local recall state.
+
+See [Compaction](/docs/compaction) for in-session context management and [Settings](/docs/settings) for config locations, project overrides, and precedence.