nodmix 2026.5.25

package/docs/concepts/markdown-formatting.md

@@ -0,0 +1,139 @@
+---
+summary: "Markdown formatting pipeline for outbound channels"
+read_when:
+  - You are changing markdown formatting or chunking for outbound channels
+  - You are adding a new channel formatter or style mapping
+  - You are debugging formatting regressions across channels
+title: "Markdown formatting"
+---
+
+Nodmix formats outbound Markdown by converting it into a shared intermediate
+representation (IR) before rendering channel-specific output. The IR keeps the
+source text intact while carrying style/link spans so chunking and rendering can
+stay consistent across channels.
+
+## Goals
+
+- **Consistency:** one parse step, multiple renderers.
+- **Safe chunking:** split text before rendering so inline formatting never
+  breaks across chunks.
+- **Channel fit:** map the same IR to Slack mrkdwn, Telegram HTML, and Signal
+  style ranges without re-parsing Markdown.
+
+## Pipeline
+
+1. **Parse Markdown -> IR**
+   - IR is plain text plus style spans (bold/italic/strike/code/spoiler) and link spans.
+   - Offsets are UTF-16 code units so Signal style ranges align with its API.
+   - Tables are parsed only when a channel opts into table conversion.
+2. **Chunk IR (format-first)**
+   - Chunking happens on the IR text before rendering.
+   - Inline formatting does not split across chunks; spans are sliced per chunk.
+3. **Render per channel**
+   - **Slack:** mrkdwn tokens (bold/italic/strike/code), links as `<url|label>`.
+   - **Telegram:** HTML tags (`<b>`, `<i>`, `<s>`, `<code>`, `<pre><code>`, `<a href>`).
+   - **Signal:** plain text + `text-style` ranges; links become `label (url)` when label differs.
+
+## IR example
+
+Input Markdown:
+
+```markdown
+Hello **world** - see [docs](https://docs.nodmix.ai).
+```
+
+IR (schematic):
+
+```json
+{
+  "text": "Hello world - see docs.",
+  "styles": [{ "start": 6, "end": 11, "style": "bold" }],
+  "links": [{ "start": 19, "end": 23, "href": "https://docs.nodmix.ai" }]
+}
+```
+
+## Where it is used
+
+- Slack, Telegram, and Signal outbound adapters render from the IR.
+- Other channels (WhatsApp, iMessage, Microsoft Teams, Discord) still use plain text or
+  their own formatting rules, with Markdown table conversion applied before
+  chunking when enabled.
+
+## Table handling
+
+Markdown tables are not consistently supported across chat clients. Use
+`markdown.tables` to control conversion per channel (and per account).
+
+- `code`: render tables as code blocks (default for most channels).
+- `bullets`: convert each row into bullet points (default for Matrix, Signal, and WhatsApp).
+- `off`: disable table parsing and conversion; raw table text passes through.
+
+Config keys:
+
+```yaml
+channels:
+  discord:
+    markdown:
+      tables: code
+    accounts:
+      work:
+        markdown:
+          tables: off
+```
+
+## Chunking rules
+
+- Chunk limits come from channel adapters/config and are applied to the IR text.
+- Code fences are preserved as a single block with a trailing newline so channels
+  render them correctly.
+- List prefixes and blockquote prefixes are part of the IR text, so chunking
+  does not split mid-prefix.
+- Inline styles (bold/italic/strike/inline-code/spoiler) are never split across
+  chunks; the renderer reopens styles inside each chunk.
+
+If you need more on chunking behavior across channels, see
+[Streaming + chunking](/concepts/streaming).
+
+## Link policy
+
+- **Slack:** `[label](url)` -> `<url|label>`; bare URLs remain bare. Autolink
+  is disabled during parse to avoid double-linking.
+- **Telegram:** `[label](url)` -> `<a href="url">label</a>` (HTML parse mode).
+- **Signal:** `[label](url)` -> `label (url)` unless label matches the URL.
+
+## Spoilers
+
+Spoiler markers (`||spoiler||`) are parsed only for Signal, where they map to
+SPOILER style ranges. Other channels treat them as plain text.
+
+## How to add or update a channel formatter
+
+1. **Parse once:** use the shared `markdownToIR(...)` helper with channel-appropriate
+   options (autolink, heading style, blockquote prefix).
+2. **Render:** implement a renderer with `renderMarkdownWithMarkers(...)` and a
+   style marker map (or Signal style ranges).
+3. **Chunk:** call `chunkMarkdownIR(...)` before rendering; render each chunk.
+4. **Wire adapter:** update the channel outbound adapter to use the new chunker
+   and renderer.
+5. **Test:** add or update format tests and an outbound delivery test if the
+   channel uses chunking.
+
+## Common gotchas
+
+- Slack angle-bracket tokens (`<@U123>`, `<#C123>`, `<https://...>`) must be
+  preserved; escape raw HTML safely.
+- Telegram HTML requires escaping text outside tags to avoid broken markup.
+- Signal style ranges depend on UTF-16 offsets; do not use code point offsets.
+- Preserve trailing newlines for fenced code blocks so closing markers land on
+  their own line.
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Streaming and chunking" href="/concepts/streaming" icon="bars-staggered">
+    Outbound streaming behavior, chunk boundaries, and channel-specific delivery.
+  </Card>
+  <Card title="System prompt" href="/concepts/system-prompt" icon="message-lines">
+    What the model sees before the conversation, including injected workspace files.
+  </Card>
+</CardGroup>

package/docs/concepts/memory-builtin.md

@@ -0,0 +1,146 @@
+---
+summary: "The default SQLite-based memory backend with keyword, vector, and hybrid search"
+title: "Builtin memory engine"
+read_when:
+  - You want to understand the default memory backend
+  - You want to configure embedding providers or hybrid search
+---
+
+The builtin engine is the default memory backend. It stores your memory index in
+a per-agent SQLite database and needs no extra dependencies to get started.
+
+## What it provides
+
+- **Keyword search** via FTS5 full-text indexing (BM25 scoring).
+- **Vector search** via embeddings from any supported provider.
+- **Hybrid search** that combines both for best results.
+- **CJK support** via trigram tokenization for Chinese, Japanese, and Korean.
+- **sqlite-vec acceleration** for in-database vector queries (optional).
+
+## Getting started
+
+If you have an API key for OpenAI, Gemini, Voyage, Mistral, or DeepInfra, the builtin
+engine auto-detects it and enables vector search. No config needed.
+
+To set a provider explicitly:
+
+```json5
+{
+  agents: {
+    defaults: {
+      memorySearch: {
+        provider: "openai",
+      },
+    },
+  },
+}
+```
+
+Without an embedding provider, only keyword search is available.
+
+To force the built-in local embedding provider, install the optional
+`node-llama-cpp` runtime package next to Nodmix, then point `local.modelPath`
+at a GGUF file:
+
+```json5
+{
+  agents: {
+    defaults: {
+      memorySearch: {
+        provider: "local",
+        fallback: "none",
+        local: {
+          modelPath: "~/.node-llama-cpp/models/embeddinggemma-300m-qat-Q8_0.gguf",
+        },
+      },
+    },
+  },
+}
+```
+
+## Supported embedding providers
+
+| Provider  | ID          | Auto-detected | Notes                               |
+| --------- | ----------- | ------------- | ----------------------------------- |
+| OpenAI    | `openai`    | Yes           | Default: `text-embedding-3-small`   |
+| Gemini    | `gemini`    | Yes           | Supports multimodal (image + audio) |
+| Voyage    | `voyage`    | Yes           |                                     |
+| Mistral   | `mistral`   | Yes           |                                     |
+| DeepInfra | `deepinfra` | Yes           | Default: `BAAI/bge-m3`              |
+| Ollama    | `ollama`    | No            | Local, set explicitly               |
+| Local     | `local`     | Yes (first)   | Optional `node-llama-cpp` runtime   |
+
+Auto-detection picks the first provider whose API key can be resolved, in the
+order shown. Set `memorySearch.provider` to override.
+
+## How indexing works
+
+Nodmix indexes `MEMORY.md` and `memory/*.md` into chunks (~400 tokens with
+80-token overlap) and stores them in a per-agent SQLite database.
+
+- **Index location:** `~/.nodmix/memory/<agentId>.sqlite`
+- **Storage maintenance:** SQLite WAL sidecars are bounded with periodic and
+  shutdown checkpoints.
+- **File watching:** changes to memory files trigger a debounced reindex (1.5s).
+- **Auto-reindex:** when the embedding provider, model, or chunking config
+  changes, the entire index is rebuilt automatically.
+- **Reindex on demand:** `nodmix memory index --force`
+
+<Info>
+You can also index Markdown files outside the workspace with
+`memorySearch.extraPaths`. See the
+[configuration reference](/reference/memory-config#additional-memory-paths).
+</Info>
+
+## When to use
+
+The builtin engine is the right choice for most users:
+
+- Works out of the box with no extra dependencies.
+- Handles keyword and vector search well.
+- Supports all embedding providers.
+- Hybrid search combines the best of both retrieval approaches.
+
+Consider switching to [QMD](/concepts/memory-qmd) if you need reranking, query
+expansion, or want to index directories outside the workspace.
+
+Consider [Honcho](/concepts/memory-honcho) if you want cross-session memory with
+automatic user modeling.
+
+## Troubleshooting
+
+**Memory search disabled?** Check `nodmix memory status`. If no provider is
+detected, set one explicitly or add an API key.
+
+**Local provider not detected?** Confirm the local path exists and run:
+
+```bash
+nodmix memory status --deep --agent main
+nodmix memory index --force --agent main
+```
+
+Both standalone CLI commands and the Gateway use the same `local` provider id.
+If the provider is set to `auto`, local embeddings are considered first only
+when `memorySearch.local.modelPath` points to an existing local file.
+
+**Stale results?** Run `nodmix memory index --force` to rebuild. The watcher
+may miss changes in rare edge cases.
+
+**sqlite-vec not loading?** Nodmix falls back to in-process cosine similarity
+automatically. `nodmix memory status --deep` reports the local vector store
+separately from the embedding provider, so `Vector store: unavailable` points
+at sqlite-vec loading while `Embeddings: unavailable` points at provider/auth
+or model readiness. Check logs for the specific load error.
+
+## Configuration
+
+For embedding provider setup, hybrid search tuning (weights, MMR, temporal
+decay), batch indexing, multimodal memory, sqlite-vec, extra paths, and all
+other config knobs, see the
+[Memory configuration reference](/reference/memory-config).
+
+## Related
+
+- [Memory overview](/concepts/memory)
+- [Memory search](/concepts/memory-search)
+- [Active memory](/concepts/active-memory)

package/docs/concepts/memory-honcho.md

@@ -0,0 +1,144 @@
+---
+summary: "AI-native cross-session memory via the Honcho plugin"
+title: "Honcho memory"
+read_when:
+  - You want persistent memory that works across sessions and channels
+  - You want AI-powered recall and user modeling
+---
+
+[Honcho](https://honcho.dev) adds AI-native memory to Nodmix. It persists
+conversations to a dedicated service and builds user and agent models over time,
+giving your agent cross-session context that goes beyond workspace Markdown
+files.
+
+## What it provides
+
+- **Cross-session memory** -- conversations are persisted after every turn, so
+  context carries across session resets, compaction, and channel switches.
+- **User modeling** -- Honcho maintains a profile for each user (preferences,
+  facts, communication style) and for the agent (personality, learned
+  behaviors).
+- **Semantic search** -- search over observations from past conversations, not
+  just the current session.
+- **Multi-agent awareness** -- parent agents automatically track spawned
+  sub-agents, with parents added as observers in child sessions.
+
+## Available tools
+
+Honcho registers tools that the agent can use during conversation:
+
+**Data retrieval (fast, no LLM call):**
+
+| Tool                        | What it does                                           |
+| --------------------------- | ------------------------------------------------------ |
+| `honcho_context`            | Full user representation across sessions               |
+| `honcho_search_conclusions` | Semantic search over stored conclusions                |
+| `honcho_search_messages`    | Find messages across sessions (filter by sender, date) |
+| `honcho_session`            | Current session history and summary                    |
+
+**Q&A (LLM-powered):**
+
+| Tool         | What it does                                                              |
+| ------------ | ------------------------------------------------------------------------- |
+| `honcho_ask` | Ask about the user. `depth='quick'` for facts, `'thorough'` for synthesis |
+
+## Getting started
+
+Install the plugin and run setup:
+
+```bash
+nodmix plugins install @honcho-ai/nodmix-honcho
+nodmix honcho setup
+nodmix gateway --force
+```
+
+The setup command prompts for your API credentials, writes the config, and
+optionally migrates existing workspace memory files.
+
+<Info>
+Honcho can run entirely locally (self-hosted) or via the managed API at
+`api.honcho.dev`. No external dependencies are required for the self-hosted
+option.
+</Info>
+
+## Configuration
+
+Settings live under `plugins.entries["nodmix-honcho"].config`:
+
+```json5
+{
+  plugins: {
+    entries: {
+      "nodmix-honcho": {
+        config: {
+          apiKey: "your-api-key", // omit for self-hosted
+          workspaceId: "nodmix", // memory isolation
+          baseUrl: "https://api.honcho.dev",
+        },
+      },
+    },
+  },
+}
+```
+
+For self-hosted instances, point `baseUrl` to your local server (for example
+`http://localhost:8000`) and omit the API key.
+
+## Migrating existing memory
+
+If you have existing workspace memory files (`USER.md`, `MEMORY.md`,
+`IDENTITY.md`, `memory/`, `canvas/`), `nodmix honcho setup` detects and
+offers to migrate them.
+
+<Info>
+Migration is non-destructive -- files are uploaded to Honcho. Originals are
+never deleted or moved.
+</Info>
+
+## How it works
+
+After every AI turn, the conversation is persisted to Honcho. Both user and
+agent messages are observed, allowing Honcho to build and refine its models over
+time.
+
+During conversation, Honcho tools query the service in the `before_prompt_build`
+phase, injecting relevant context before the model sees the prompt. This ensures
+accurate turn boundaries and relevant recall.
+
+## Honcho vs builtin memory
+
+|                   | Builtin / QMD                | Honcho                              |
+| ----------------- | ---------------------------- | ----------------------------------- |
+| **Storage**       | Workspace Markdown files     | Dedicated service (local or hosted) |
+| **Cross-session** | Via memory files             | Automatic, built-in                 |
+| **User modeling** | Manual (write to MEMORY.md)  | Automatic profiles                  |
+| **Search**        | Vector + keyword (hybrid)    | Semantic over observations          |
+| **Multi-agent**   | Not tracked                  | Parent/child awareness              |
+| **Dependencies**  | None (builtin) or QMD binary | Plugin install                      |
+
+Honcho and the builtin memory system can work together. When QMD is configured,
+additional tools become available for searching local Markdown files alongside
+Honcho's cross-session memory.
+
+## CLI commands
+
+```bash
+nodmix honcho setup                        # Configure API key and migrate files
+nodmix honcho status                       # Check connection status
+nodmix honcho ask <question>               # Query Honcho about the user
+nodmix honcho search <query> [-k N] [-d D] # Semantic search over memory
+```
+
+## Further reading
+
+- [Plugin source code](https://github.com/plastic-labs/nodmix-honcho)
+- [Honcho documentation](https://docs.honcho.dev)
+- [Honcho Nodmix integration guide](https://docs.honcho.dev/v3/guides/integrations/nodmix)
+- [Memory](/concepts/memory) -- Nodmix memory overview
+- [Context Engines](/concepts/context-engine) -- how plugin context engines work
+
+## Related
+
+- [Memory overview](/concepts/memory)
+- [Builtin memory engine](/concepts/memory-builtin)
+- [QMD memory engine](/concepts/memory-qmd)

package/docs/concepts/memory-qmd.md

@@ -0,0 +1,271 @@
+---
+summary: "Local-first search sidecar with BM25, vectors, reranking, and query expansion"
+title: "QMD memory engine"
+read_when:
+  - You want to set up QMD as your memory backend
+  - You want advanced memory features like reranking or extra indexed paths
+---
+
+[QMD](https://github.com/tobi/qmd) is a local-first search sidecar that runs
+alongside Nodmix. It combines BM25, vector search, and reranking in a single
+binary, and can index content beyond your workspace memory files.
+
+## What it adds over builtin
+
+- **Reranking and query expansion** for better recall.
+- **Index extra directories** -- project docs, team notes, anything on disk.
+- **Index session transcripts** -- recall earlier conversations.
+- **Fully local** -- runs with the optional node-llama-cpp runtime package and
+  auto-downloads GGUF models.
+- **Automatic fallback** -- if QMD is unavailable, Nodmix falls back to the
+  builtin engine seamlessly.
+
+## Getting started
+
+### Prerequisites
+
+- Install QMD: `npm install -g @tobilu/qmd` or `bun install -g @tobilu/qmd`
+- SQLite build that allows extensions (`brew install sqlite` on macOS).
+- QMD must be on the gateway's `PATH`.
+- macOS and Linux work out of the box. Windows is best supported via WSL2.
+
+### Enable
+
+```json5
+{
+  memory: {
+    backend: "qmd",
+  },
+}
+```
+
+Nodmix creates a self-contained QMD home under
+`~/.nodmix/agents/<agentId>/qmd/` and manages the sidecar lifecycle
+automatically -- collections, updates, and embedding runs are handled for you.
+It prefers current QMD collection and MCP query shapes, but still falls back to
+alternate collection pattern flags and older MCP tool names when needed.
+Boot-time reconciliation also recreates stale managed collections back to their
+canonical patterns when an older QMD collection with the same name is still
+present.
+
+## How the sidecar works
+
+- Nodmix creates collections from your workspace memory files and any
+  configured `memory.qmd.paths`, then runs `qmd update` when the QMD manager is
+  opened and periodically afterward (default every 5 minutes). These refreshes
+  run through QMD subprocesses, not an in-process filesystem crawl. Semantic
+  modes also run `qmd embed`.
+- The default workspace collection tracks `MEMORY.md` plus the `memory/`
+  tree. Lowercase `memory.md` is not indexed as a root memory file.
+- QMD's own scanner ignores hidden paths and common dependency/build
+  directories such as `.git`, `.cache`, `node_modules`, `vendor`, `dist`, and
+  `build`. Gateway startup does not initialize QMD by default, so cold boot
+  avoids importing the memory runtime or creating the long-lived watcher before
+  memory is first used.
+- If you want a gateway-start refresh anyway, set
+  `memory.qmd.update.startup` to `idle` or `immediate`. The opt-in startup
+  refresh uses a one-shot QMD subprocess path instead of creating the full
+  long-lived in-process watcher.
+- Searches use the configured `searchMode` (default: `search`; also supports
+  `vsearch` and `query`). `search` is BM25-only, so Nodmix skips semantic
+  vector readiness probes and embedding maintenance in that mode. If a mode
+  fails, Nodmix retries with `qmd query`.
+- With QMD releases that advertise multi-collection filters, Nodmix groups
+  same-source collections into one QMD search invocation. Older QMD releases
+  keep the compatible per-collection fallback.
+- If QMD fails entirely, Nodmix falls back to the builtin SQLite engine.
+  Repeated chat-turn attempts back off briefly after an open failure so a
+  missing binary or broken sidecar dependency does not create a retry storm;
+  `nodmix memory status` and one-shot CLI probes still recheck QMD directly.
+
+<Info>
+The first search may be slow -- QMD auto-downloads GGUF models (~2 GB) for
+reranking and query expansion on the first `qmd query` run.
+</Info>
+
+## Search performance and compatibility
+
+Nodmix keeps the QMD search path compatible with both current and older QMD
+installs.
+
+On startup, Nodmix checks the installed QMD help text once per manager. If the
+binary advertises support for multiple collection filters, Nodmix searches all
+same-source collections with one command:
+
+```bash
+qmd search "router notes" --json -n 10 -c memory-root-main -c memory-dir-main
+```
+
+This avoids starting one QMD subprocess for every durable-memory collection.
+Session transcript collections stay in their own source group, so mixed
+`memory` + `sessions` searches still give the result diversifier input from both
+sources.
+
+Older QMD builds only accept one collection filter. When Nodmix detects one
+of those builds, it keeps the compatibility path and searches each collection
+separately before merging and deduplicating results.
+
+To inspect the installed contract manually, run:
+
+```bash
+qmd --help | grep -i collection
+```
+
+Current QMD help says collection filters can target one or more collections.
+Older help usually describes a single collection.
+
+## Model overrides
+
+QMD model environment variables pass through unchanged from the gateway
+process, so you can tune QMD globally without adding new Nodmix config:
+
+```bash
+export QMD_EMBED_MODEL="hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf"
+export QMD_RERANK_MODEL="/absolute/path/to/reranker.gguf"
+export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf"
+```
+
+After changing the embedding model, rerun embeddings so the index matches the
+new vector space.
+
+## Indexing extra paths
+
+Point QMD at additional directories to make them searchable:
+
+```json5
+{
+  memory: {
+    backend: "qmd",
+    qmd: {
+      paths: [{ name: "docs", path: "~/notes", pattern: "**/*.md" }],
+    },
+  },
+}
+```
+
+Snippets from extra paths appear as `qmd/<collection>/<relative-path>` in
+search results. `memory_get` understands this prefix and reads from the correct
+collection root.
+
+## Indexing session transcripts
+
+Enable session indexing to recall earlier conversations:
+
+```json5
+{
+  memory: {
+    backend: "qmd",
+    qmd: {
+      sessions: { enabled: true },
+    },
+  },
+}
+```
+
+Transcripts are exported as sanitized User/Assistant turns into a dedicated QMD
+collection under `~/.nodmix/agents/<id>/qmd/sessions/`.
+
+## Search scope
+
+By default, QMD search results are surfaced in direct and channel sessions
+(not groups). Configure `memory.qmd.scope` to change this:
+
+```json5
+{
+  memory: {
+    qmd: {
+      scope: {
+        default: "deny",
+        rules: [{ action: "allow", match: { chatType: "direct" } }],
+      },
+    },
+  },
+}
+```
+
+When scope denies a search, Nodmix logs a warning with the derived channel and
+chat type so empty results are easier to debug.
+
+## Citations
+
+When `memory.citations` is `auto` or `on`, search snippets include a
+`Source: <path#line>` footer. Set `memory.citations = "off"` to omit the footer
+while still passing the path to the agent internally.
+
+## When to use
+
+Choose QMD when you need:
+
+- Reranking for higher-quality results.
+- To search project docs or notes outside the workspace.
+- To recall past session conversations.
+- Fully local search with no API keys.
+
+For simpler setups, the [builtin engine](/concepts/memory-builtin) works well
+with no extra dependencies.
+
+## Troubleshooting
+
+**QMD not found?** Ensure the binary is on the gateway's `PATH`. If Nodmix
+runs as a service, create a symlink:
+`sudo ln -s ~/.bun/bin/qmd /usr/local/bin/qmd`.
+
+If `qmd --version` works in your shell but Nodmix still reports
+`spawn qmd ENOENT`, the gateway process likely has a different `PATH` than your
+interactive shell. Pin the binary explicitly:
+
+```json5
+{
+  memory: {
+    backend: "qmd",
+    qmd: {
+      command: "/absolute/path/to/qmd",
+    },
+  },
+}
+```
+
+Use `command -v qmd` in the environment where QMD is installed, then recheck
+with `nodmix memory status --deep`.
+
+**First search very slow?** QMD downloads GGUF models on first use. Pre-warm
+with `qmd query "test"` using the same XDG dirs Nodmix uses.
+
+**Many QMD subprocesses during search?** Update QMD if possible. Nodmix uses
+one process for same-source multi-collection searches only when the installed
+QMD advertises support for multiple `-c` filters; otherwise it keeps the older
+per-collection fallback for correctness.
+
+**BM25-only QMD still trying to build llama.cpp?** Set
+`memory.qmd.searchMode = "search"`. Nodmix treats that mode as lexical-only,
+does not run QMD vector status probes or embedding maintenance, and leaves
+semantic readiness checks to `vsearch` or `query` setups.
+
+**Search times out?** Increase `memory.qmd.limits.timeoutMs` (default: 4000ms).
+Set to `120000` for slower hardware.
+
+**Empty results in group chats?** Check `memory.qmd.scope` -- the default only
+allows direct and channel sessions.
+
+**Root memory search suddenly got too broad?** Restart the gateway or wait for
+the next startup reconciliation. Nodmix recreates stale managed collections
+back to canonical `MEMORY.md` and `memory/` patterns when it detects a same-name
+conflict.
+
+**Workspace-visible temp repos causing `ENAMETOOLONG` or broken indexing?**
+QMD traversal currently follows the underlying QMD scanner behavior rather than
+Nodmix's builtin symlink rules. Keep temporary monorepo checkouts under
+hidden directories like `.tmp/` or outside indexed QMD roots until QMD exposes
+cycle-safe traversal or explicit exclusion controls.
+
+## Configuration
+
+For the full config surface (`memory.qmd.*`), search modes, update intervals,
+scope rules, and all other knobs, see the
+[Memory configuration reference](/reference/memory-config).
+
+## Related
+
+- [Memory overview](/concepts/memory)
+- [Builtin memory engine](/concepts/memory-builtin)
+- [Honcho memory](/concepts/memory-honcho)