durar-ai 2026.4.4

package/docs/concepts/memory-builtin.md

@@ -0,0 +1,105 @@
+---
+title: "Builtin Memory Engine"
+summary: "The default SQLite-based memory backend with keyword, vector, and hybrid search"
+read_when:
+  - You want to understand the default memory backend
+  - You want to configure embedding providers or hybrid search
+---
+
+# Builtin Memory Engine
+
+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, or Mistral, 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.
+
+## 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           |                                     |
+| Ollama   | `ollama`  | No            | Local, set explicitly               |
+| Local    | `local`   | Yes (first)   | GGUF model, ~0.6 GB download        |
+
+Auto-detection picks the first provider whose API key can be resolved, in the
+order shown. Set `memorySearch.provider` to override.
+
+## How indexing works
+
+Durar 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:** `~/.Durar/memory/<agentId>.sqlite`
+- **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:** `Durar 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 `Durar memory status`. If no provider is
+detected, set one explicitly or add an API key.
+
+**Stale results?** Run `Durar memory index --force` to rebuild. The watcher
+may miss changes in rare edge cases.
+
+**sqlite-vec not loading?** Durar falls back to in-process cosine similarity
+automatically. 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).

package/docs/concepts/memory-honcho.md

@@ -0,0 +1,140 @@
+---
+title: "Honcho Memory"
+summary: "AI-native cross-session memory via the Honcho plugin"
+read_when:
+  - You want persistent memory that works across sessions and channels
+  - You want AI-powered recall and user modeling
+---
+
+# Honcho Memory
+
+[Honcho](https://honcho.dev) adds AI-native memory to Durar. 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
+Durar plugins install @honcho-ai/Durar-honcho
+Durar honcho setup
+Durar 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["Durar-honcho"].config`:
+
+```json5
+{
+  plugins: {
+    entries: {
+      "Durar-honcho": {
+        config: {
+          apiKey: "your-api-key", // omit for self-hosted
+          workspaceId: "Durar", // 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/`), `Durar 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
+Durar honcho setup                        # Configure API key and migrate files
+Durar honcho status                       # Check connection status
+Durar honcho ask <question>               # Query Honcho about the user
+Durar honcho search <query> [-k N] [-d D] # Semantic search over memory
+```
+
+## Further reading
+
+- [Plugin source code](https://github.com/plastic-labs/Durar-honcho)
+- [Honcho documentation](https://docs.honcho.dev)
+- [Honcho Durar integration guide](https://docs.honcho.dev/v3/guides/integrations/Durar)
+- [Memory](/concepts/memory) -- Durar memory overview
+- [Context Engines](/concepts/context-engine) -- how plugin context engines work

package/docs/concepts/memory-qmd.md

@@ -0,0 +1,163 @@
+---
+title: "QMD Memory Engine"
+summary: "Local-first search sidecar with BM25, vectors, reranking, and query expansion"
+read_when:
+  - You want to set up QMD as your memory backend
+  - You want advanced memory features like reranking or extra indexed paths
+---
+
+# QMD Memory Engine
+
+[QMD](https://github.com/tobi/qmd) is a local-first search sidecar that runs
+alongside Durar. 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 via Bun + node-llama-cpp, auto-downloads GGUF models.
+- **Automatic fallback** -- if QMD is unavailable, Durar falls back to the
+  builtin engine seamlessly.
+
+## Getting started
+
+### Prerequisites
+
+- Install QMD: `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",
+  },
+}
+```
+
+Durar creates a self-contained QMD home under
+`~/.Durar/agents/<agentId>/qmd/` and manages the sidecar lifecycle
+automatically -- collections, updates, and embedding runs are handled for you.
+
+## How the sidecar works
+
+- Durar creates collections from your workspace memory files and any
+  configured `memory.qmd.paths`, then runs `qmd update` + `qmd embed` on boot
+  and periodically (default every 5 minutes).
+- Boot refresh runs in the background so chat startup is not blocked.
+- Searches use the configured `searchMode` (default: `search`; also supports
+  `vsearch` and `query`). If a mode fails, Durar retries with `qmd query`.
+- If QMD fails entirely, Durar falls back to the builtin SQLite engine.
+
+<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>
+
+## 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 `~/.Durar/agents/<id>/qmd/sessions/`.
+
+## Search scope
+
+By default, QMD search results are only surfaced in DM sessions (not groups or
+channels). Configure `memory.qmd.scope` to change this:
+
+```json5
+{
+  memory: {
+    qmd: {
+      scope: {
+        default: "deny",
+        rules: [{ action: "allow", match: { chatType: "direct" } }],
+      },
+    },
+  },
+}
+```
+
+When scope denies a search, Durar 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 Durar
+runs as a service, create a symlink:
+`sudo ln -s ~/.bun/bin/qmd /usr/local/bin/qmd`.
+
+**First search very slow?** QMD downloads GGUF models on first use. Pre-warm
+with `qmd query "test"` using the same XDG dirs Durar uses.
+
+**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 DM sessions.
+
+**Workspace-visible temp repos causing `ENAMETOOLONG` or broken indexing?**
+QMD traversal currently follows the underlying QMD scanner behavior rather than
+Durar'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).

package/docs/concepts/memory-search.md

@@ -0,0 +1,141 @@
+---
+title: "Memory Search"
+summary: "How memory search finds relevant notes using embeddings and hybrid retrieval"
+read_when:
+  - You want to understand how memory_search works
+  - You want to choose an embedding provider
+  - You want to tune search quality
+---
+
+# Memory Search
+
+`memory_search` finds relevant notes from your memory files, even when the
+wording differs from the original text. It works by indexing memory into small
+chunks and searching them using embeddings, keywords, or both.
+
+## Quick start
+
+If you have an OpenAI, Gemini, Voyage, or Mistral API key configured, memory
+search works automatically. To set a provider explicitly:
+
+```json5
+{
+  agents: {
+    defaults: {
+      memorySearch: {
+        provider: "openai", // or "gemini", "local", "ollama", etc.
+      },
+    },
+  },
+}
+```
+
+For local embeddings with no API key, use `provider: "local"` (requires
+node-llama-cpp).
+
+## Supported providers
+
+| Provider | ID        | Needs API key | Notes                         |
+| -------- | --------- | ------------- | ----------------------------- |
+| OpenAI   | `openai`  | Yes           | Auto-detected, fast           |
+| Gemini   | `gemini`  | Yes           | Supports image/audio indexing |
+| Voyage   | `voyage`  | Yes           | Auto-detected                 |
+| Mistral  | `mistral` | Yes           | Auto-detected                 |
+| Ollama   | `ollama`  | No            | Local, must set explicitly    |
+| Local    | `local`   | No            | GGUF model, ~0.6 GB download  |
+
+## How search works
+
+Durar runs two retrieval paths in parallel and merges the results:
+
+```mermaid
+flowchart LR
+    Q["Query"] --> E["Embedding"]
+    Q --> T["Tokenize"]
+    E --> VS["Vector Search"]
+    T --> BM["BM25 Search"]
+    VS --> M["Weighted Merge"]
+    BM --> M
+    M --> R["Top Results"]
+```
+
+- **Vector search** finds notes with similar meaning ("gateway host" matches
+  "the machine running Durar").
+- **BM25 keyword search** finds exact matches (IDs, error strings, config
+  keys).
+
+If only one path is available (no embeddings or no FTS), the other runs alone.
+
+## Improving search quality
+
+Two optional features help when you have a large note history:
+
+### Temporal decay
+
+Old notes gradually lose ranking weight so recent information surfaces first.
+With the default half-life of 30 days, a note from last month scores at 50% of
+its original weight. Evergreen files like `MEMORY.md` are never decayed.
+
+<Tip>
+Enable temporal decay if your agent has months of daily notes and stale
+information keeps outranking recent context.
+</Tip>
+
+### MMR (diversity)
+
+Reduces redundant results. If five notes all mention the same router config, MMR
+ensures the top results cover different topics instead of repeating.
+
+<Tip>
+Enable MMR if `memory_search` keeps returning near-duplicate snippets from
+different daily notes.
+</Tip>
+
+### Enable both
+
+```json5
+{
+  agents: {
+    defaults: {
+      memorySearch: {
+        query: {
+          hybrid: {
+            mmr: { enabled: true },
+            temporalDecay: { enabled: true },
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+## Multimodal memory
+
+With Gemini Embedding 2, you can index images and audio files alongside
+Markdown. Search queries remain text, but they match against visual and audio
+content. See the [Memory configuration reference](/reference/memory-config) for
+setup.
+
+## Session memory search
+
+You can optionally index session transcripts so `memory_search` can recall
+earlier conversations. This is opt-in via
+`memorySearch.experimental.sessionMemory`. See the
+[configuration reference](/reference/memory-config) for details.
+
+## Troubleshooting
+
+**No results?** Run `Durar memory status` to check the index. If empty, run
+`Durar memory index --force`.
+
+**Only keyword matches?** Your embedding provider may not be configured. Check
+`Durar memory status --deep`.
+
+**CJK text not found?** Rebuild the FTS index with
+`Durar memory index --force`.
+
+## Further reading
+
+- [Memory](/concepts/memory) -- file layout, backends, tools
+- [Memory configuration reference](/reference/memory-config) -- all config knobs

package/docs/concepts/memory.md

@@ -0,0 +1,121 @@
+---
+title: "Memory Overview"
+summary: "How Durar remembers things across sessions"
+read_when:
+  - You want to understand how memory works
+  - You want to know what memory files to write
+---
+
+# Memory Overview
+
+Durar remembers things by writing **plain Markdown files** in your agent's
+workspace. The model only "remembers" what gets saved to disk -- there is no
+hidden state.
+
+## How it works
+
+Your agent has two places to store memories:
+
+- **`MEMORY.md`** -- long-term memory. Durable facts, preferences, and
+  decisions. Loaded at the start of every DM session.
+- **`memory/YYYY-MM-DD.md`** -- daily notes. Running context and observations.
+  Today and yesterday's notes are loaded automatically.
+
+These files live in the agent workspace (default `~/.Durar/workspace`).
+
+<Tip>
+If you want your agent to remember something, just ask it: "Remember that I
+prefer TypeScript." It will write it to the appropriate file.
+</Tip>
+
+## Memory tools
+
+The agent has two tools for working with memory:
+
+- **`memory_search`** -- finds relevant notes using semantic search, even when
+  the wording differs from the original.
+- **`memory_get`** -- reads a specific memory file or line range.
+
+Both tools are provided by the active memory plugin (default: `memory-core`).
+
+## Memory search
+
+When an embedding provider is configured, `memory_search` uses **hybrid
+search** -- combining vector similarity (semantic meaning) with keyword matching
+(exact terms like IDs and code symbols). This works out of the box once you have
+an API key for any supported provider.
+
+<Info>
+Durar auto-detects your embedding provider from available API keys. If you
+have an OpenAI, Gemini, Voyage, or Mistral key configured, memory search is
+enabled automatically.
+</Info>
+
+For details on how search works, tuning options, and provider setup, see
+[Memory Search](/concepts/memory-search).
+
+## Memory backends
+
+<CardGroup cols={3}>
+<Card title="Builtin (default)" icon="database" href="/concepts/memory-builtin">
+SQLite-based. Works out of the box with keyword search, vector similarity, and
+hybrid search. No extra dependencies.
+</Card>
+<Card title="QMD" icon="search" href="/concepts/memory-qmd">
+Local-first sidecar with reranking, query expansion, and the ability to index
+directories outside the workspace.
+</Card>
+<Card title="Honcho" icon="brain" href="/concepts/memory-honcho">
+AI-native cross-session memory with user modeling, semantic search, and
+multi-agent awareness. Plugin install.
+</Card>
+</CardGroup>
+
+## Automatic memory flush
+
+Before [compaction](/concepts/compaction) summarizes your conversation, Durar
+runs a silent turn that reminds the agent to save important context to memory
+files. This is on by default -- you do not need to configure anything.
+
+<Tip>
+The memory flush prevents context loss during compaction. If your agent has
+important facts in the conversation that are not yet written to a file, they
+will be saved automatically before the summary happens.
+</Tip>
+
+## Dreaming (experimental)
+
+Dreaming is an optional background consolidation pass for memory. It revisits
+short-term recalls from daily files (`memory/YYYY-MM-DD.md`), scores them, and
+promotes only qualified items into long-term memory (`MEMORY.md`).
+
+It is designed to keep long-term memory high signal:
+
+- **Opt-in**: disabled by default.
+- **Scheduled**: when enabled, `memory-core` manages the recurring task
+  automatically.
+- **Thresholded**: promotions must pass score, recall frequency, and query
+  diversity gates.
+
+For mode behavior (`off`, `core`, `rem`, `deep`), scoring signals, and tuning
+knobs, see [Dreaming (experimental)](/concepts/dreaming).
+
+## CLI
+
+```bash
+Durar memory status          # Check index status and provider
+Durar memory search "query"  # Search from the command line
+Durar memory index --force   # Rebuild the index
+```
+
+## Further reading
+
+- [Builtin Memory Engine](/concepts/memory-builtin) -- default SQLite backend
+- [QMD Memory Engine](/concepts/memory-qmd) -- advanced local-first sidecar
+- [Honcho Memory](/concepts/memory-honcho) -- AI-native cross-session memory
+- [Memory Search](/concepts/memory-search) -- search pipeline, providers, and
+  tuning
+- [Dreaming (experimental)](/concepts/dreaming) -- background promotion
+  from short-term recall to long-term memory
+- [Memory configuration reference](/reference/memory-config) -- all config knobs
+- [Compaction](/concepts/compaction) -- how compaction interacts with memory