fix: include AccountId in telegram native command context (#2942) (thanks @Chloe-VP)

When running multiple Telegram bot accounts bound to different agents,
the /new command (and other slash commands) would send confirmation
messages via the wrong bot because the context was missing AccountId.

The fix adds AccountId: route.accountId to the context payload in
registerTelegramNativeCommands, matching how bot-message-context.ts
handles regular messages.

Fixes #2537

CHANGELOG.md

@@ -13,6 +13,7 @@ Status: beta.
 - Branding: update launchd labels, mobile bundle IDs, and logging subsystems to bot.molt (legacy com.clawdbot migrations). Thanks @thewilloftheshadow.
 - Tools: add per-sender group tool policies and fix precedence. (#1757) Thanks @adam91holt.
 - Agents: summarize dropped messages during compaction safeguard pruning. (#2509) Thanks @jogi47.
+- Memory Search: allow extra paths for memory indexing (ignores symlinks). (#3600) Thanks @kira-ariaki.
 - Skills: add multi-image input support to Nano Banana Pro skill. (#1958) Thanks @tyler6204.
 - Agents: honor tools.exec.safeBins in exec allowlist checks. (#2281)
 - Matrix: switch plugin SDK to @vector-im/matrix-bot-sdk.
@@ -77,6 +78,9 @@ Status: beta.
 - Agents: prevent retries on oversized image errors and surface size limits. (#2871) Thanks @Suksham-sharma.
 - Agents: inherit provider baseUrl/api for inline models. (#2740) Thanks @lploc94.
 - Memory Search: keep auto provider model defaults and only include remote when configured. (#2576) Thanks @papago2355.
+- Telegram: include AccountId in native command context for multi-agent routing. (#2942) Thanks @Chloe-VP.
+- Telegram: handle video note attachments in media extraction. (#2905) Thanks @mylukin.
+- TTS: read OPENAI_TTS_BASE_URL at runtime instead of module load to honor config.env. (#3341) Thanks @hclsys.
 - macOS: auto-scroll to bottom when sending a new message while scrolled up. (#2471) Thanks @kennyklee.
 - Web UI: auto-expand the chat compose textarea while typing (with sensible max height). (#2950) Thanks @shivamraut101.
 - Gateway: prevent crashes on transient network errors (fetch failures, timeouts, DNS). Added fatal error detection to only exit on truly critical errors. Fixes #2895, #2879, #2873. (#2980) Thanks @elliotsecops.
@@ -106,6 +110,7 @@ Status: beta.
 - Telegram: centralize API error logging for delivery and bot calls. (#2492) Thanks @altryne.
 - Voice Call: enforce Twilio webhook signature verification for ngrok URLs; disable ngrok free tier bypass by default.
 - Security: harden Tailscale Serve auth by validating identity via local tailscaled before trusting headers.
+- Media: fix text attachment MIME misclassification with CSV/TSV inference and UTF-16 detection; add XML attribute escaping for file output. (#3628) Thanks @frankekn.
 - Build: align memory-core peer dependency with lockfile.
 - Security: add mDNS discovery mode with minimal default to reduce information disclosure. (#1882) Thanks @orlyjamie.
 - Security: harden URL fetches with DNS pinning to reduce rebinding risk. Thanks Chris Zheng.

docs/channels/whatsapp.md

@@ -125,7 +125,7 @@ the prefix (use `""` to remove it).
 - **DM policy**: `channels.whatsapp.dmPolicy` controls direct chat access (default: `pairing`).
   - Pairing: unknown senders get a pairing code (approve via `moltbot pairing approve whatsapp <code>`; codes expire after 1 hour).
   - Open: requires `channels.whatsapp.allowFrom` to include `"*"`.
-  - Self messages are always allowed; “self-chat mode” still requires `channels.whatsapp.allowFrom` to include your own number.
+  - Your linked WhatsApp number is implicitly trusted, so self messages skip ⁠`channels.whatsapp.dmPolicy` and `channels.whatsapp.allowFrom` checks.
 
 ### Personal-number mode (fallback)
 If you run Moltbot on your **personal WhatsApp number**, enable `channels.whatsapp.selfChatMode` (see sample above).

docs/cli/memory.md

@@ -39,3 +39,4 @@ Notes:
 - `memory status --deep` probes vector + embedding availability.
 - `memory status --deep --index` runs a reindex if the store is dirty.
 - `memory index --verbose` prints per-phase details (provider, model, sources, batch activity).
+- `memory status` includes any extra paths configured via `memorySearch.extraPaths`.

docs/concepts/memory.md

@@ -75,8 +75,9 @@ For the full compaction lifecycle, see
 
 ## Vector memory search
 
-Moltbot can build a small vector index over `MEMORY.md` and `memory/*.md` so
-semantic queries can find related notes even when wording differs.
+Moltbot can build a small vector index over `MEMORY.md` and `memory/*.md` (plus
+any extra directories or files you opt in) so semantic queries can find related
+notes even when wording differs.
 
 Defaults:
 - Enabled by default.
@@ -96,118 +97,26 @@ embeddings for memory search. For Gemini, use `GEMINI_API_KEY` or
 `models.providers.google.apiKey`. When using a custom OpenAI-compatible endpoint,
 set `memorySearch.remote.apiKey` (and optional `memorySearch.remote.headers`).
 
-### QMD backend (experimental)
+### Additional memory paths
 
-Set `memory.backend = "qmd"` to swap the built-in SQLite indexer for
-[QMD](https://github.com/tobi/qmd): a local-first search sidecar that combines
-BM25 + vectors + reranking. Markdown stays the source of truth; Moltbot shells
-out to QMD for retrieval. Key points:
-
-**Prereqs**
-- Disabled by default. Opt in per-config (`memory.backend = "qmd"`).
-- Install the QMD CLI separately (`bun install -g github.com/tobi/qmd` or grab
-  a release) and make sure the `qmd` binary is on the gateway’s `PATH`.
-- QMD needs an SQLite build that allows extensions (`brew install sqlite` on
-  macOS).
-- QMD runs fully locally via Bun + `node-llama-cpp` and auto-downloads GGUF
-  models from HuggingFace on first use (no separate Ollama daemon required).
-- The gateway runs QMD in a self-contained XDG home under
-  `~/.clawdbot/agents/<agentId>/qmd/` by setting `XDG_CONFIG_HOME` and
-  `XDG_CACHE_HOME`.
-- OS support: macOS and Linux work out of the box once Bun + SQLite are
-  installed. Windows is best supported via WSL2.
-
-**How the sidecar runs**
-- The gateway writes a self-contained QMD home under
-  `~/.clawdbot/agents/<agentId>/qmd/` (config + cache + sqlite DB).
-- Collections are rewritten from `memory.qmd.paths` (plus default workspace
-  memory files) into `index.yml`, then `qmd update` + `qmd embed` run on boot and
-  on a configurable interval (`memory.qmd.update.interval`, default 5 m).
-- Searches run via `qmd query --json`. If QMD fails or the binary is missing,
-  Moltbot automatically falls back to the builtin SQLite manager so memory tools
-  keep working.
-- **First search may be slow**: QMD may download local GGUF models (reranker/query
-  expansion) on the first `qmd query` run.
-  - Moltbot sets `XDG_CONFIG_HOME`/`XDG_CACHE_HOME` automatically when it runs QMD.
-  - If you want to pre-download models manually (and warm the same index Moltbot
-    uses), run a one-off query with the agent’s XDG dirs.
-
-    Moltbot’s QMD state lives under your **state dir** (usually `~/.clawdbot`, or
-    `~/.moltbot` on newer installs). You can point `qmd` at the exact same index
-    by exporting the same XDG vars Moltbot uses:
-
-    ```bash
-    # Pick the same state dir Moltbot uses
-    STATE_DIR="${MOLTBOT_STATE_DIR:-${CLAWDBOT_STATE_DIR:-$HOME/.clawdbot}}"
-    if [ -d "$HOME/.moltbot" ] && [ ! -d "$HOME/.clawdbot" ] \
-      && [ -z "${MOLTBOT_STATE_DIR:-}" ] && [ -z "${CLAWDBOT_STATE_DIR:-}" ]; then
-      STATE_DIR="$HOME/.moltbot"
-    fi
-
-    export XDG_CONFIG_HOME="$STATE_DIR/agents/main/qmd/xdg-config"
-    export XDG_CACHE_HOME="$STATE_DIR/agents/main/qmd/xdg-cache"
-
-    # (Optional) force an index refresh + embeddings
-    qmd update
-    qmd embed
-
-    # Warm up / trigger first-time model downloads
-    qmd query "test" -c memory-root --json >/dev/null 2>&1
-    ```
-
-**Config surface (`memory.qmd.*`)**
-- `command` (default `qmd`): override the executable path.
-- `includeDefaultMemory` (default `true`): auto-index `MEMORY.md` + `memory/**/*.md`.
-- `paths[]`: add extra directories/files (`path`, optional `pattern`, optional
-  stable `name`).
-- `sessions`: opt into session JSONL indexing (`enabled`, `retentionDays`,
-  `exportDir`).
-- `update`: controls refresh cadence (`interval`, `debounceMs`, `onBoot`, `embedInterval`).
-- `limits`: clamp recall payload (`maxResults`, `maxSnippetChars`,
-  `maxInjectedChars`, `timeoutMs`).
-- `scope`: same schema as [`session.sendPolicy`](/reference/configuration#session-sendpolicy).
-  Default is DM-only (`deny` all, `allow` direct chats); loosen it to surface QMD
-  hits in groups/channels.
-- Snippets sourced outside the workspace show up as
-  `qmd/<collection>/<relative-path>` in `memory_search` results; `memory_get`
-  understands that prefix and reads from the configured QMD collection root.
-- When `memory.qmd.sessions.enabled = true`, Moltbot exports sanitized session
-  transcripts (User/Assistant turns) into a dedicated QMD collection under
-  `~/.clawdbot/agents/<id>/qmd/sessions/`, so `memory_search` can recall recent
-  conversations without touching the builtin SQLite index.
-- `memory_search` snippets now include a `Source: <path#line>` footer when
-  `memory.citations` is `auto`/`on`; set `memory.citations = "off"` to keep
-  the path metadata internal (the agent still receives the path for
-  `memory_get`, but the snippet text omits the footer and the system prompt
-  warns the agent not to cite it).
-
-**Example**
+If you want to index Markdown files outside the default workspace layout, add
+explicit paths:
 
 ```json5
-memory: {
-  backend: "qmd",
-  citations: "auto",
-  qmd: {
-    includeDefaultMemory: true,
-    update: { interval: "5m", debounceMs: 15000 },
-    limits: { maxResults: 6, timeoutMs: 4000 },
-    scope: {
-      default: "deny",
-      rules: [{ action: "allow", match: { chatType: "direct" } }]
-    },
-    paths: [
-      { name: "docs", path: "~/notes", pattern: "**/*.md" }
-    ]
+agents: {
+  defaults: {
+    memorySearch: {
+      extraPaths: ["../team-docs", "/srv/shared-notes/overview.md"]
+    }
   }
 }
 ```
 
-**Citations & fallback**
-- `memory.citations` applies regardless of backend (`auto`/`on`/`off`).
-- When `qmd` runs, we tag `status().backend = "qmd"` so diagnostics show which
-  engine served the results. If the QMD subprocess exits or JSON output can’t be
-  parsed, the search manager logs a warning and returns the builtin provider
-  (existing Markdown embeddings) until QMD recovers.
+Notes:
+- Paths can be absolute or workspace-relative.
+- Directories are scanned recursively for `.md` files.
+- Only Markdown files are indexed.
+- Symlinks are ignored (files or directories).
 
 ### Gemini embeddings (native)
 
@@ -302,14 +211,14 @@ Local mode:
 ### How the memory tools work
 
 - `memory_search` semantically searches Markdown chunks (~400 token target, 80-token overlap) from `MEMORY.md` + `memory/**/*.md`. It returns snippet text (capped ~700 chars), file path, line range, score, provider/model, and whether we fell back from local → remote embeddings. No full file payload is returned.
-- `memory_get` reads a specific memory Markdown file (workspace-relative), optionally from a starting line and for N lines. Paths outside `MEMORY.md` / `memory/` are rejected.
+- `memory_get` reads a specific memory Markdown file (workspace-relative), optionally from a starting line and for N lines. Paths outside `MEMORY.md` / `memory/` are allowed only when explicitly listed in `memorySearch.extraPaths`.
 - Both tools are enabled only when `memorySearch.enabled` resolves true for the agent.
 
 ### What gets indexed (and when)
 
-- File type: Markdown only (`MEMORY.md`, `memory/**/*.md`).
+- File type: Markdown only (`MEMORY.md`, `memory/**/*.md`, plus any `.md` files under `memorySearch.extraPaths`).
 - Index storage: per-agent SQLite at `~/.clawdbot/memory/<agentId>.sqlite` (configurable via `agents.defaults.memorySearch.store.path`, supports `{agentId}` token).
-- Freshness: watcher on `MEMORY.md` + `memory/` marks the index dirty (debounce 1.5s). Sync is scheduled on session start, on search, or on an interval and runs asynchronously. Session transcripts use delta thresholds to trigger background sync.
+- Freshness: watcher on `MEMORY.md`, `memory/`, and `memorySearch.extraPaths` marks the index dirty (debounce 1.5s). Sync is scheduled on session start, on search, or on an interval and runs asynchronously. Session transcripts use delta thresholds to trigger background sync.
 - Reindex triggers: the index stores the embedding **provider/model + endpoint fingerprint + chunking params**. If any of those change, Moltbot automatically resets and reindexes the entire store.
 
 ### Hybrid search (BM25 + vector)

docs/gateway/configuration-examples.md

@@ -267,7 +267,8 @@ Save to `~/.clawdbot/moltbot.json` and you can DM the bot from that number.
         model: "gemini-embedding-001",
         remote: {
           apiKey: "${GEMINI_API_KEY}"
-        }
+        },
+        extraPaths: ["../team-docs", "/srv/shared-notes"]
       },
       sandbox: {
         mode: "non-main",

docs/providers/venice.md

@@ -4,9 +4,9 @@ read_when:
   - You want privacy-focused inference in Moltbot
   - You want Venice AI setup guidance
 ---
-# Venice AI (Venius highlight)
+# Venice AI (Venice highlight)
 
-**Venius** is our highlight Venice setup for privacy-first inference with optional anonymized access to proprietary models.
+**Venice** is our highlight Venice setup for privacy-first inference with optional anonymized access to proprietary models.
 
 Venice AI provides privacy-focused AI inference with support for uncensored models and access to major proprietary models through their anonymized proxy. All inference is private by default—no training on your data, no logging.
 

src/agents/cli-runner/helpers.ts

@@ -212,7 +212,6 @@ export function buildSystemPrompt(params: {
     userTimeFormat,
     contextFiles: params.contextFiles,
     ttsHint,
-    memoryCitationsMode: params.config?.memory?.citations,
   });
 }
 

src/agents/memory-search.test.ts

@@ -82,6 +82,29 @@ describe("memory search config", () => {
     expect(resolved?.store.vector.extensionPath).toBe("/opt/sqlite-vec.dylib");
   });
 
+  it("merges extra memory paths from defaults and overrides", () => {
+    const cfg = {
+      agents: {
+        defaults: {
+          memorySearch: {
+            extraPaths: ["/shared/notes", " docs "],
+          },
+        },
+        list: [
+          {
+            id: "main",
+            default: true,
+            memorySearch: {
+              extraPaths: ["/shared/notes", "../team-notes"],
+            },
+          },
+        ],
+      },
+    };
+    const resolved = resolveMemorySearchConfig(cfg, "main");
+    expect(resolved?.extraPaths).toEqual(["/shared/notes", "docs", "../team-notes"]);
+  });
+
   it("includes batch defaults for openai without remote overrides", () => {
     const cfg = {
       agents: {

src/agents/memory-search.ts

@@ -9,6 +9,7 @@ import { resolveAgentConfig } from "./agent-scope.js";
 export type ResolvedMemorySearchConfig = {
   enabled: boolean;
   sources: Array<"memory" | "sessions">;
+  extraPaths: string[];
   provider: "openai" | "local" | "gemini" | "auto";
   remote?: {
     baseUrl?: string;
@@ -162,6 +163,10 @@ function mergeConfig(
     modelCacheDir: overrides?.local?.modelCacheDir ?? defaults?.local?.modelCacheDir,
   };
   const sources = normalizeSources(overrides?.sources ?? defaults?.sources, sessionMemory);
+  const rawPaths = [...(defaults?.extraPaths ?? []), ...(overrides?.extraPaths ?? [])]
+    .map((value) => value.trim())
+    .filter(Boolean);
+  const extraPaths = Array.from(new Set(rawPaths));
   const vector = {
     enabled: overrides?.store?.vector?.enabled ?? defaults?.store?.vector?.enabled ?? true,
     extensionPath:
@@ -236,6 +241,7 @@ function mergeConfig(
   return {
     enabled,
     sources,
+    extraPaths,
     provider,
     remote,
     experimental: {

src/agents/pi-embedded-runner/compact.ts

@@ -346,7 +346,6 @@ export async function compactEmbeddedPiSessionDirect(
       userTime,
       userTimeFormat,
       contextFiles,
-      memoryCitationsMode: params.config?.memory?.citations,
     });
     const systemPrompt = createSystemPromptOverride(appendPrompt);
 

src/agents/pi-embedded-runner/run/attempt.ts

@@ -359,7 +359,6 @@ export async function runEmbeddedAttempt(
       userTime,
       userTimeFormat,
       contextFiles,
-      memoryCitationsMode: params.config?.memory?.citations,
     });
     const systemPromptReport = buildSystemPromptReport({
       source: "run",

src/agents/pi-embedded-runner/system-prompt.ts

@@ -1,5 +1,4 @@
 import type { AgentTool } from "@mariozechner/pi-agent-core";
-import type { MemoryCitationsMode } from "../../config/types.memory.js";
 import type { ResolvedTimeFormat } from "../date-time.js";
 import type { EmbeddedContextFile } from "../pi-embedded-helpers.js";
 import { buildAgentSystemPrompt, type PromptMode } from "../system-prompt.js";
@@ -46,7 +45,6 @@ export function buildEmbeddedSystemPrompt(params: {
   userTime?: string;
   userTimeFormat?: ResolvedTimeFormat;
   contextFiles?: EmbeddedContextFile[];
-  memoryCitationsMode?: MemoryCitationsMode;
 }): string {
   return buildAgentSystemPrompt({
     workspaceDir: params.workspaceDir,
@@ -72,7 +70,6 @@ export function buildEmbeddedSystemPrompt(params: {
     userTime: params.userTime,
     userTimeFormat: params.userTimeFormat,
     contextFiles: params.contextFiles,
-    memoryCitationsMode: params.memoryCitationsMode,
   });
 }
 

src/agents/system-prompt.ts

@@ -1,7 +1,6 @@
 import type { ReasoningLevel, ThinkLevel } from "../auto-reply/thinking.js";
 import { SILENT_REPLY_TOKEN } from "../auto-reply/tokens.js";
 import { listDeliverableMessageChannels } from "../utils/message-channel.js";
-import type { MemoryCitationsMode } from "../config/types.memory.js";
 import type { ResolvedTimeFormat } from "./date-time.js";
 import type { EmbeddedContextFile } from "./pi-embedded-helpers.js";
 
@@ -33,30 +32,16 @@ function buildSkillsSection(params: {
   ];
 }
 
-function buildMemorySection(params: {
-  isMinimal: boolean;
-  availableTools: Set<string>;
-  citationsMode?: MemoryCitationsMode;
-}) {
+function buildMemorySection(params: { isMinimal: boolean; availableTools: Set<string> }) {
   if (params.isMinimal) return [];
   if (!params.availableTools.has("memory_search") && !params.availableTools.has("memory_get")) {
     return [];
   }
-  const lines = [
+  return [
     "## Memory Recall",
     "Before answering anything about prior work, decisions, dates, people, preferences, or todos: run memory_search on MEMORY.md + memory/*.md; then use memory_get to pull only the needed lines. If low confidence after search, say you checked.",
+    "",
   ];
-  if (params.citationsMode === "off") {
-    lines.push(
-      "Citations are disabled: do not mention file paths or line numbers in replies unless the user explicitly asks.",
-    );
-  } else {
-    lines.push(
-      "Citations: include Source: <path#line> when it helps the user verify memory snippets.",
-    );
-  }
-  lines.push("");
-  return lines;
 }
 
 function buildUserIdentitySection(ownerLine: string | undefined, isMinimal: boolean) {
@@ -193,7 +178,6 @@ export function buildAgentSystemPrompt(params: {
     level: "minimal" | "extensive";
     channel: string;
   };
-  memoryCitationsMode?: MemoryCitationsMode;
 }) {
   const coreToolSummaries: Record<string, string> = {
     read: "Read file contents",
@@ -330,11 +314,7 @@ export function buildAgentSystemPrompt(params: {
     isMinimal,
     readToolName,
   });
-  const memorySection = buildMemorySection({
-    isMinimal,
-    availableTools,
-    citationsMode: params.memoryCitationsMode,
-  });
+  const memorySection = buildMemorySection({ isMinimal, availableTools });
   const docsSection = buildDocsSection({
     docsPath: params.docsPath,
     isMinimal,

src/agents/tools/memory-tool.citations.test.ts

@@ -1,65 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
-
-const stubManager = {
-  search: vi.fn(async () => [
-    {
-      path: "MEMORY.md",
-      startLine: 5,
-      endLine: 7,
-      score: 0.9,
-      snippet: "@@ -5,3 @@\nAssistant: noted",
-      source: "memory" as const,
-    },
-  ]),
-  readFile: vi.fn(),
-  status: () => ({
-    backend: "builtin" as const,
-    files: 1,
-    chunks: 1,
-    dirty: false,
-    workspaceDir: "/workspace",
-    dbPath: "/workspace/.memory/index.sqlite",
-    provider: "builtin",
-    model: "builtin",
-    requestedProvider: "builtin",
-    sources: ["memory" as const],
-    sourceCounts: [{ source: "memory" as const, files: 1, chunks: 1 }],
-  }),
-  sync: vi.fn(),
-  probeVectorAvailability: vi.fn(async () => true),
-  close: vi.fn(),
-};
-
-vi.mock("../../memory/index.js", () => {
-  return {
-    getMemorySearchManager: async () => ({ manager: stubManager }),
-  };
-});
-
-import { createMemorySearchTool } from "./memory-tool.js";
-
-beforeEach(() => {
-  vi.clearAllMocks();
-});
-
-describe("memory search citations", () => {
-  it("appends source information when citations are enabled", async () => {
-    const cfg = { memory: { citations: "on" }, agents: { list: [{ id: "main", default: true }] } };
-    const tool = createMemorySearchTool({ config: cfg });
-    if (!tool) throw new Error("tool missing");
-    const result = await tool.execute("call_citations_on", { query: "notes" });
-    const details = result.details as { results: Array<{ snippet: string; citation?: string }> };
-    expect(details.results[0]?.snippet).toMatch(/Source: MEMORY.md#L5-L7/);
-    expect(details.results[0]?.citation).toBe("MEMORY.md#L5-L7");
-  });
-
-  it("leaves snippet untouched when citations are off", async () => {
-    const cfg = { memory: { citations: "off" }, agents: { list: [{ id: "main", default: true }] } };
-    const tool = createMemorySearchTool({ config: cfg });
-    if (!tool) throw new Error("tool missing");
-    const result = await tool.execute("call_citations_off", { query: "notes" });
-    const details = result.details as { results: Array<{ snippet: string; citation?: string }> };
-    expect(details.results[0]?.snippet).not.toMatch(/Source:/);
-    expect(details.results[0]?.citation).toBeUndefined();
-  });
-});

src/agents/tools/memory-tool.ts

@@ -1,9 +1,7 @@
 import { Type } from "@sinclair/typebox";
 
 import type { MoltbotConfig } from "../../config/config.js";
-import type { MemoryCitationsMode } from "../../config/types.memory.js";
 import { getMemorySearchManager } from "../../memory/index.js";
-import type { MemorySearchResult } from "../../memory/types.js";
 import { resolveSessionAgentId } from "../agent-scope.js";
 import { resolveMemorySearchConfig } from "../memory-search.js";
 import type { AnyAgentTool } from "./common.js";
@@ -50,24 +48,17 @@ export function createMemorySearchTool(options: {
         return jsonResult({ results: [], disabled: true, error });
       }
       try {
-        const citationsMode = resolveMemoryCitationsMode(cfg);
-        const includeCitations = shouldIncludeCitations({
-          mode: citationsMode,
-          sessionKey: options.agentSessionKey,
-        });
-        const rawResults = await manager.search(query, {
+        const results = await manager.search(query, {
           maxResults,
           minScore,
           sessionKey: options.agentSessionKey,
         });
         const status = manager.status();
-        const results = decorateCitations(rawResults, includeCitations);
         return jsonResult({
           results,
           provider: status.provider,
           model: status.model,
           fallback: status.fallback,
-          citations: citationsMode,
         });
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
@@ -92,7 +83,7 @@ export function createMemoryGetTool(options: {
     label: "Memory Get",
     name: "memory_get",
     description:
-      "Safe snippet read from MEMORY.md or memory/*.md with optional from/lines; use after memory_search to pull only the needed lines and keep context small.",
+      "Safe snippet read from MEMORY.md, memory/*.md, or configured memorySearch.extraPaths with optional from/lines; use after memory_search to pull only the needed lines and keep context small.",
     parameters: MemoryGetSchema,
     execute: async (_toolCallId, params) => {
       const relPath = readStringParam(params, "path", { required: true });
@@ -119,46 +110,3 @@ export function createMemoryGetTool(options: {
     },
   };
 }
-
-function resolveMemoryCitationsMode(cfg: MoltbotConfig): MemoryCitationsMode {
-  const mode = cfg.memory?.citations;
-  if (mode === "on" || mode === "off" || mode === "auto") return mode;
-  return "auto";
-}
-
-function decorateCitations(results: MemorySearchResult[], include: boolean): MemorySearchResult[] {
-  if (!include) {
-    return results.map((entry) => ({ ...entry, citation: undefined }));
-  }
-  return results.map((entry) => {
-    const citation = formatCitation(entry);
-    const snippet = `${entry.snippet.trim()}\n\nSource: ${citation}`;
-    return { ...entry, citation, snippet };
-  });
-}
-
-function formatCitation(entry: MemorySearchResult): string {
-  const lineRange =
-    entry.startLine === entry.endLine
-      ? `#L${entry.startLine}`
-      : `#L${entry.startLine}-L${entry.endLine}`;
-  return `${entry.path}${lineRange}`;
-}
-
-function shouldIncludeCitations(params: {
-  mode: MemoryCitationsMode;
-  sessionKey?: string;
-}): boolean {
-  if (params.mode === "on") return true;
-  if (params.mode === "off") return false;
-  // auto: show citations in direct chats; suppress in groups/channels by default.
-  const chatType = deriveChatTypeFromSessionKey(params.sessionKey);
-  return chatType === "direct";
-}
-
-function deriveChatTypeFromSessionKey(sessionKey?: string): "direct" | "group" | "channel" {
-  if (!sessionKey) return "direct";
-  if (sessionKey.includes(":group:")) return "group";
-  if (sessionKey.includes(":channel:")) return "channel";
-  return "direct";
-}

src/auto-reply/reply/commands-context-report.ts

@@ -150,7 +150,6 @@ async function resolveContextReport(
     ttsHint,
     runtimeInfo,
     sandboxInfo,
-    memoryCitationsMode: params.cfg?.memory?.citations,
   });
 
   return buildSystemPromptReport({

src/auto-reply/reply/dispatch-from-config.test.ts

@@ -138,7 +138,7 @@ describe("dispatchReplyFromConfig", () => {
     );
   });
 
-  it("does not provide onToolResult when routing cross-provider", async () => {
+  it("provides onToolResult in DM sessions", async () => {
     mocks.tryFastAbortFromMessage.mockResolvedValue({
       handled: false,
       aborted: false,
@@ -147,9 +147,34 @@ describe("dispatchReplyFromConfig", () => {
     const cfg = {} as MoltbotConfig;
     const dispatcher = createDispatcher();
     const ctx = buildTestCtx({
-      Provider: "slack",
-      OriginatingChannel: "telegram",
-      OriginatingTo: "telegram:999",
+      Provider: "telegram",
+      ChatType: "direct",
+    });
+
+    const replyResolver = async (
+      _ctx: MsgContext,
+      opts: GetReplyOptions | undefined,
+      _cfg: ClawdbotConfig,
+    ) => {
+      expect(opts?.onToolResult).toBeDefined();
+      expect(typeof opts?.onToolResult).toBe("function");
+      return { text: "hi" } satisfies ReplyPayload;
+    };
+
+    await dispatchReplyFromConfig({ ctx, cfg, dispatcher, replyResolver });
+    expect(dispatcher.sendFinalReply).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not provide onToolResult in group sessions", async () => {
+    mocks.tryFastAbortFromMessage.mockResolvedValue({
+      handled: false,
+      aborted: false,
+    });
+    const cfg = {} as ClawdbotConfig;
+    const dispatcher = createDispatcher();
+    const ctx = buildTestCtx({
+      Provider: "telegram",
+      ChatType: "group",
     });
 
     const replyResolver = async (
@@ -162,12 +187,62 @@ describe("dispatchReplyFromConfig", () => {
     };
 
     await dispatchReplyFromConfig({ ctx, cfg, dispatcher, replyResolver });
+    expect(dispatcher.sendFinalReply).toHaveBeenCalledTimes(1);
+  });
 
-    expect(mocks.routeReply).toHaveBeenCalledWith(
-      expect.objectContaining({
-        payload: expect.objectContaining({ text: "hi" }),
-      }),
+  it("sends tool results via dispatcher in DM sessions", async () => {
+    mocks.tryFastAbortFromMessage.mockResolvedValue({
+      handled: false,
+      aborted: false,
+    });
+    const cfg = {} as ClawdbotConfig;
+    const dispatcher = createDispatcher();
+    const ctx = buildTestCtx({
+      Provider: "telegram",
+      ChatType: "direct",
+    });
+
+    const replyResolver = async (
+      _ctx: MsgContext,
+      opts: GetReplyOptions | undefined,
+      _cfg: ClawdbotConfig,
+    ) => {
+      // Simulate tool result emission
+      await opts?.onToolResult?.({ text: "🔧 exec: ls" });
+      return { text: "done" } satisfies ReplyPayload;
+    };
+
+    await dispatchReplyFromConfig({ ctx, cfg, dispatcher, replyResolver });
+    expect(dispatcher.sendToolResult).toHaveBeenCalledWith(
+      expect.objectContaining({ text: "🔧 exec: ls" }),
     );
+    expect(dispatcher.sendFinalReply).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not provide onToolResult for native slash commands", async () => {
+    mocks.tryFastAbortFromMessage.mockResolvedValue({
+      handled: false,
+      aborted: false,
+    });
+    const cfg = {} as ClawdbotConfig;
+    const dispatcher = createDispatcher();
+    const ctx = buildTestCtx({
+      Provider: "telegram",
+      ChatType: "direct",
+      CommandSource: "native",
+    });
+
+    const replyResolver = async (
+      _ctx: MsgContext,
+      opts: GetReplyOptions | undefined,
+      _cfg: ClawdbotConfig,
+    ) => {
+      expect(opts?.onToolResult).toBeUndefined();
+      return { text: "hi" } satisfies ReplyPayload;
+    };
+
+    await dispatchReplyFromConfig({ ctx, cfg, dispatcher, replyResolver });
+    expect(dispatcher.sendFinalReply).toHaveBeenCalledTimes(1);
   });
 
   it("fast-aborts without calling the reply resolver", async () => {

src/auto-reply/reply/dispatch-from-config.ts

@@ -276,6 +276,27 @@ export async function dispatchReplyFromConfig(params: {
       ctx,
       {
         ...params.replyOptions,
+        onToolResult:
+          ctx.ChatType !== "group" && ctx.CommandSource !== "native"
+            ? (payload: ReplyPayload) => {
+                const run = async () => {
+                  const ttsPayload = await maybeApplyTtsToPayload({
+                    payload,
+                    cfg,
+                    channel: ttsChannel,
+                    kind: "tool",
+                    inboundAudio,
+                    ttsAuto: sessionTtsAuto,
+                  });
+                  if (shouldRouteToOriginating) {
+                    await sendPayloadAsync(ttsPayload, undefined, false);
+                  } else {
+                    dispatcher.sendToolResult(ttsPayload);
+                  }
+                };
+                return run();
+              }
+            : undefined,
         onBlockReply: (payload: ReplyPayload, context) => {
           const run = async () => {
             // Accumulate block text for TTS generation after streaming

src/cli/banner.ts

@@ -71,6 +71,7 @@ const LOBSTER_ASCII = [
   "██░███░██░▀▀▀░██░▀▀░███░████░▀▀░██░▀▀▀░███░████",
   "▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀",
   "               🦞 FRESH DAILY 🦞               ",
+  " ",
 ];
 
 export function formatCliBannerArt(options: BannerOptions = {}): string {

src/cli/memory-cli.test.ts

@@ -242,7 +242,7 @@ describe("memory cli", () => {
     await program.parseAsync(["memory", "status", "--index"], { from: "user" });
 
     expect(sync).toHaveBeenCalledWith(
-      expect.objectContaining({ reason: "cli", force: false, progress: expect.any(Function) }),
+      expect.objectContaining({ reason: "cli", progress: expect.any(Function) }),
     );
     expect(probeEmbeddingAvailability).toHaveBeenCalled();
     expect(close).toHaveBeenCalled();

src/cli/memory-cli.ts

@@ -12,7 +12,7 @@ import { setVerbose } from "../globals.js";
 import { withProgress, withProgressTotals } from "./progress.js";
 import { formatErrorMessage, withManager } from "./cli-utils.js";
 import { getMemorySearchManager, type MemorySearchManagerResult } from "../memory/index.js";
-import { listMemoryFiles } from "../memory/internal.js";
+import { listMemoryFiles, normalizeExtraMemoryPaths } from "../memory/internal.js";
 import { defaultRuntime } from "../runtime.js";
 import { formatDocsLink } from "../terminal/links.js";
 import { colorize, isRich, theme } from "../terminal/theme.js";
@@ -24,7 +24,6 @@ type MemoryCommandOptions = {
   json?: boolean;
   deep?: boolean;
   index?: boolean;
-  force?: boolean;
   verbose?: boolean;
 };
 
@@ -75,6 +74,10 @@ function resolveAgentIds(cfg: ReturnType<typeof loadConfig>, agent?: string): st
   return [resolveDefaultAgentId(cfg)];
 }
 
+function formatExtraPaths(workspaceDir: string, extraPaths: string[]): string[] {
+  return normalizeExtraMemoryPaths(workspaceDir, extraPaths).map((entry) => shortenHomePath(entry));
+}
+
 async function checkReadableFile(pathname: string): Promise<{ exists: boolean; issue?: string }> {
   try {
     await fs.access(pathname, fsSync.constants.R_OK);
@@ -111,7 +114,10 @@ async function scanSessionFiles(agentId: string): Promise<SourceScan> {
   }
 }
 
-async function scanMemoryFiles(workspaceDir: string): Promise<SourceScan> {
+async function scanMemoryFiles(
+  workspaceDir: string,
+  extraPaths: string[] = [],
+): Promise<SourceScan> {
   const issues: string[] = [];
   const memoryFile = path.join(workspaceDir, "MEMORY.md");
   const altMemoryFile = path.join(workspaceDir, "memory.md");
@@ -122,6 +128,25 @@ async function scanMemoryFiles(workspaceDir: string): Promise<SourceScan> {
   if (primary.issue) issues.push(primary.issue);
   if (alt.issue) issues.push(alt.issue);
 
+  const resolvedExtraPaths = normalizeExtraMemoryPaths(workspaceDir, extraPaths);
+  for (const extraPath of resolvedExtraPaths) {
+    try {
+      const stat = await fs.lstat(extraPath);
+      if (stat.isSymbolicLink()) continue;
+      const extraCheck = await checkReadableFile(extraPath);
+      if (extraCheck.issue) issues.push(extraCheck.issue);
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code === "ENOENT") {
+        issues.push(`additional memory path missing (${shortenHomePath(extraPath)})`);
+      } else {
+        issues.push(
+          `additional memory path not accessible (${shortenHomePath(extraPath)}): ${code ?? "error"}`,
+        );
+      }
+    }
+  }
+
   let dirReadable: boolean | null = null;
   try {
     await fs.access(memoryDir, fsSync.constants.R_OK);
@@ -142,7 +167,7 @@ async function scanMemoryFiles(workspaceDir: string): Promise<SourceScan> {
   let listed: string[] = [];
   let listedOk = false;
   try {
-    listed = await listMemoryFiles(workspaceDir);
+    listed = await listMemoryFiles(workspaceDir, resolvedExtraPaths);
     listedOk = true;
   } catch (err) {
     const code = (err as NodeJS.ErrnoException).code;
@@ -177,11 +202,13 @@ async function scanMemorySources(params: {
   workspaceDir: string;
   agentId: string;
   sources: MemorySourceName[];
+  extraPaths?: string[];
 }): Promise<MemorySourceScan> {
   const scans: SourceScan[] = [];
+  const extraPaths = params.extraPaths ?? [];
   for (const source of params.sources) {
     if (source === "memory") {
-      scans.push(await scanMemoryFiles(params.workspaceDir));
+      scans.push(await scanMemoryFiles(params.workspaceDir, extraPaths));
     }
     if (source === "sessions") {
       scans.push(await scanSessionFiles(params.agentId));
@@ -214,16 +241,13 @@ export async function runMemoryStatus(opts: MemoryCommandOptions) {
       onMissing: (error) => defaultRuntime.log(error ?? "Memory search disabled."),
       onCloseError: (err) =>
         defaultRuntime.error(`Memory manager close failed: ${formatErrorMessage(err)}`),
-      close: async (manager) => {
-        await manager.close?.();
-      },
+      close: (manager) => manager.close(),
       run: async (manager) => {
         const deep = Boolean(opts.deep || opts.index);
         let embeddingProbe:
           | Awaited<ReturnType<typeof manager.probeEmbeddingAvailability>>
           | undefined;
         let indexError: string | undefined;
-        const syncFn = manager.sync ? manager.sync.bind(manager) : undefined;
         if (deep) {
           await withProgress({ label: "Checking memory…", total: 2 }, async (progress) => {
             progress.setLabel("Probing vector…");
@@ -233,7 +257,7 @@ export async function runMemoryStatus(opts: MemoryCommandOptions) {
             embeddingProbe = await manager.probeEmbeddingAvailability();
             progress.tick();
           });
-          if (opts.index && syncFn) {
+          if (opts.index) {
             await withProgressTotals(
               {
                 label: "Indexing memory…",
@@ -242,9 +266,8 @@ export async function runMemoryStatus(opts: MemoryCommandOptions) {
               },
               async (update, progress) => {
                 try {
-                  await syncFn({
+                  await manager.sync({
                     reason: "cli",
-                    force: Boolean(opts.force),
                     progress: (syncUpdate) => {
                       update({
                         completed: syncUpdate.completed,
@@ -261,8 +284,6 @@ export async function runMemoryStatus(opts: MemoryCommandOptions) {
                 }
               },
             );
-          } else if (opts.index && !syncFn) {
-            defaultRuntime.log("Memory backend does not support manual reindex.");
           }
         } else {
           await manager.probeVectorAvailability();
@@ -271,10 +292,12 @@ export async function runMemoryStatus(opts: MemoryCommandOptions) {
         const sources = (
           status.sources?.length ? status.sources : ["memory"]
         ) as MemorySourceName[];
-        const workspaceDir = status.workspaceDir;
-        const scan = workspaceDir
-          ? await scanMemorySources({ workspaceDir, agentId, sources })
-          : undefined;
+        const scan = await scanMemorySources({
+          workspaceDir: status.workspaceDir,
+          agentId,
+          sources,
+          extraPaths: status.extraPaths,
+        });
         allResults.push({ agentId, status, embeddingProbe, indexError, scan });
       },
     });
@@ -296,31 +319,28 @@ export async function runMemoryStatus(opts: MemoryCommandOptions) {
 
   for (const result of allResults) {
     const { agentId, status, embeddingProbe, indexError, scan } = result;
-    const filesIndexed = status.files ?? 0;
-    const chunksIndexed = status.chunks ?? 0;
     const totalFiles = scan?.totalFiles ?? null;
     const indexedLabel =
       totalFiles === null
-        ? `${filesIndexed}/? files · ${chunksIndexed} chunks`
-        : `${filesIndexed}/${totalFiles} files · ${chunksIndexed} chunks`;
+        ? `${status.files}/? files · ${status.chunks} chunks`
+        : `${status.files}/${totalFiles} files · ${status.chunks} chunks`;
     if (opts.index) {
       const line = indexError ? `Memory index failed: ${indexError}` : "Memory index complete.";
       defaultRuntime.log(line);
     }
-    const requestedProvider = status.requestedProvider ?? status.provider;
-    const modelLabel = status.model ?? status.provider;
-    const storePath = status.dbPath ? shortenHomePath(status.dbPath) : "<unknown>";
-    const workspacePath = status.workspaceDir ? shortenHomePath(status.workspaceDir) : "<unknown>";
-    const sourceList = status.sources?.length ? status.sources.join(", ") : null;
+    const extraPaths = formatExtraPaths(status.workspaceDir, status.extraPaths ?? []);
     const lines = [
       `${heading("Memory Search")} ${muted(`(${agentId})`)}`,
-      `${label("Provider")} ${info(status.provider)} ${muted(`(requested: ${requestedProvider})`)}`,
-      `${label("Model")} ${info(modelLabel)}`,
-      sourceList ? `${label("Sources")} ${info(sourceList)}` : null,
+      `${label("Provider")} ${info(status.provider)} ${muted(
+        `(requested: ${status.requestedProvider})`,
+      )}`,
+      `${label("Model")} ${info(status.model)}`,
+      status.sources?.length ? `${label("Sources")} ${info(status.sources.join(", "))}` : null,
+      extraPaths.length ? `${label("Extra paths")} ${info(extraPaths.join(", "))}` : null,
       `${label("Indexed")} ${success(indexedLabel)}`,
       `${label("Dirty")} ${status.dirty ? warn("yes") : muted("no")}`,
-      `${label("Store")} ${info(storePath)}`,
-      `${label("Workspace")} ${info(workspacePath)}`,
+      `${label("Store")} ${info(shortenHomePath(status.dbPath))}`,
+      `${label("Workspace")} ${info(shortenHomePath(status.workspaceDir))}`,
     ].filter(Boolean) as string[];
     if (embeddingProbe) {
       const state = embeddingProbe.ok ? "ready" : "unavailable";
@@ -333,7 +353,7 @@ export async function runMemoryStatus(opts: MemoryCommandOptions) {
     if (status.sourceCounts?.length) {
       lines.push(label("By source"));
       for (const entry of status.sourceCounts) {
-        const total = scan?.sources?.find(
+        const total = scan?.sources.find(
           (scanEntry) => scanEntry.source === entry.source,
         )?.totalFiles;
         const counts =
@@ -446,7 +466,7 @@ export function registerMemoryCli(program: Command) {
     .option("--deep", "Probe embedding provider availability")
     .option("--index", "Reindex if dirty (implies --deep)")
     .option("--verbose", "Verbose logging", false)
-    .action(async (opts: MemoryCommandOptions & { force?: boolean }) => {
+    .action(async (opts: MemoryCommandOptions) => {
       await runMemoryStatus(opts);
     });
 
@@ -456,7 +476,7 @@ export function registerMemoryCli(program: Command) {
     .option("--agent <id>", "Agent id (default: default agent)")
     .option("--force", "Force full reindex", false)
     .option("--verbose", "Verbose logging", false)
-    .action(async (opts: MemoryCommandOptions) => {
+    .action(async (opts: MemoryCommandOptions & { force?: boolean }) => {
       setVerbose(Boolean(opts.verbose));
       const cfg = loadConfig();
       const agentIds = resolveAgentIds(cfg, opts.agent);
@@ -466,12 +486,9 @@ export function registerMemoryCli(program: Command) {
           onMissing: (error) => defaultRuntime.log(error ?? "Memory search disabled."),
           onCloseError: (err) =>
             defaultRuntime.error(`Memory manager close failed: ${formatErrorMessage(err)}`),
-          close: async (manager) => {
-            await manager.close?.();
-          },
+          close: (manager) => manager.close(),
           run: async (manager) => {
             try {
-              const syncFn = manager.sync ? manager.sync.bind(manager) : undefined;
               if (opts.verbose) {
                 const status = manager.status();
                 const rich = isRich();
@@ -480,20 +497,22 @@ export function registerMemoryCli(program: Command) {
                 const info = (text: string) => colorize(rich, theme.info, text);
                 const warn = (text: string) => colorize(rich, theme.warn, text);
                 const label = (text: string) => muted(`${text}:`);
-                const sourceLabels = (status.sources ?? []).map((source) =>
-                  formatSourceLabel(source, status.workspaceDir ?? "", agentId),
+                const sourceLabels = status.sources.map((source) =>
+                  formatSourceLabel(source, status.workspaceDir, agentId),
                 );
-                const requestedProvider = status.requestedProvider ?? status.provider;
-                const modelLabel = status.model ?? status.provider;
+                const extraPaths = formatExtraPaths(status.workspaceDir, status.extraPaths ?? []);
                 const lines = [
                   `${heading("Memory Index")} ${muted(`(${agentId})`)}`,
                   `${label("Provider")} ${info(status.provider)} ${muted(
-                    `(requested: ${requestedProvider})`,
+                    `(requested: ${status.requestedProvider})`,
                   )}`,
-                  `${label("Model")} ${info(modelLabel)}`,
+                  `${label("Model")} ${info(status.model)}`,
                   sourceLabels.length
                     ? `${label("Sources")} ${info(sourceLabels.join(", "))}`
                     : null,
+                  extraPaths.length
+                    ? `${label("Extra paths")} ${info(extraPaths.join(", "))}`
+                    : null,
                 ].filter(Boolean) as string[];
                 if (status.fallback) {
                   lines.push(`${label("Fallback")} ${warn(status.fallback.from)}`);
@@ -530,10 +549,6 @@ export function registerMemoryCli(program: Command) {
                   ? `${lastLabel} · elapsed ${elapsed} · eta ${eta}`
                   : `${lastLabel} · elapsed ${elapsed}`;
               };
-              if (!syncFn) {
-                defaultRuntime.log("Memory backend does not support manual reindex.");
-                return;
-              }
               await withProgressTotals(
                 {
                   label: "Indexing memory…",
@@ -545,9 +560,9 @@ export function registerMemoryCli(program: Command) {
                     progress.setLabel(buildLabel());
                   }, 1000);
                   try {
-                    await syncFn({
+                    await manager.sync({
                       reason: "cli",
-                      force: Boolean(opts.force),
+                      force: opts.force,
                       progress: (syncUpdate) => {
                         if (syncUpdate.label) lastLabel = syncUpdate.label;
                         lastCompleted = syncUpdate.completed;
@@ -599,9 +614,7 @@ export function registerMemoryCli(program: Command) {
           onMissing: (error) => defaultRuntime.log(error ?? "Memory search disabled."),
           onCloseError: (err) =>
             defaultRuntime.error(`Memory manager close failed: ${formatErrorMessage(err)}`),
-          close: async (manager) => {
-            await manager.close?.();
-          },
+          close: (manager) => manager.close(),
           run: async (manager) => {
             let results: Awaited<ReturnType<typeof manager.search>>;
             try {

src/cli/program/register.subclis.ts

@@ -168,6 +168,11 @@ const entries: SubCliEntry[] = [
     name: "pairing",
     description: "Pairing helpers",
     register: async (program) => {
+      // Initialize plugins before registering pairing CLI.
+      // The pairing CLI calls listPairingChannels() at registration time,
+      // which requires the plugin registry to be populated with channel plugins.
+      const { registerPluginCliCommands } = await import("../../plugins/cli.js");
+      registerPluginCliCommands(program, await loadConfig());
       const mod = await import("../pairing-cli.js");
       mod.registerPairingCli(program);
     },

src/commands/onboard-helpers.ts

@@ -69,7 +69,8 @@ export function printWizardHeader(runtime: RuntimeEnv) {
     "██░█░█░██░███░██░██████░████░▄▄▀██░███░███░████",
     "██░███░██░▀▀▀░██░▀▀░███░████░▀▀░██░▀▀▀░███░████",
     "▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀",
-    "               🦞 FRESH DAILY 🦞               ",
+    "               🦞 FRESH DAILY 🦞                ",
+    " ",
   ].join("\n");
   runtime.log(header);
 }

src/commands/status.scan.ts

@@ -6,8 +6,7 @@ import { probeGateway } from "../gateway/probe.js";
 import { collectChannelStatusIssues } from "../infra/channels-status-issues.js";
 import { resolveOsSummary } from "../infra/os-summary.js";
 import { getTailnetHostname } from "../infra/tailscale.js";
-import { getMemorySearchManager } from "../memory/index.js";
-import type { MemoryProviderStatus } from "../memory/types.js";
+import type { MemoryIndexManager } from "../memory/manager.js";
 import { runExec } from "../process/exec.js";
 import type { RuntimeEnv } from "../runtime.js";
 import { getAgentLocalStatuses } from "./status.agent-local.js";
@@ -16,7 +15,7 @@ import { getStatusSummary } from "./status.summary.js";
 import { getUpdateCheckResult } from "./status.update.js";
 import { buildChannelsTable } from "./status-all/channels.js";
 
-type MemoryStatusSnapshot = MemoryProviderStatus & {
+type MemoryStatusSnapshot = ReturnType<MemoryIndexManager["status"]> & {
   agentId: string;
 };
 
@@ -152,13 +151,14 @@ export async function scanStatus(
         if (!memoryPlugin.enabled) return null;
         if (memoryPlugin.slot !== "memory-core") return null;
         const agentId = agentStatus.defaultId ?? "main";
-        const { manager } = await getMemorySearchManager({ cfg, agentId });
+        const { MemoryIndexManager } = await import("../memory/manager.js");
+        const manager = await MemoryIndexManager.get({ cfg, agentId }).catch(() => null);
         if (!manager) return null;
         try {
           await manager.probeVectorAvailability();
         } catch {}
         const status = manager.status();
-        await manager.close?.().catch(() => {});
+        await manager.close().catch(() => {});
         return { agentId, ...status };
       })();
       progress.tick();

src/config/schema.ts

@@ -222,6 +222,7 @@ const FIELD_LABELS: Record<string, string> = {
   "agents.defaults.memorySearch": "Memory Search",
   "agents.defaults.memorySearch.enabled": "Enable Memory Search",
   "agents.defaults.memorySearch.sources": "Memory Search Sources",
+  "agents.defaults.memorySearch.extraPaths": "Extra Memory Paths",
   "agents.defaults.memorySearch.experimental.sessionMemory":
     "Memory Search Session Index (Experimental)",
   "agents.defaults.memorySearch.provider": "Memory Search Provider",
@@ -252,27 +253,6 @@ const FIELD_LABELS: Record<string, string> = {
     "Memory Search Hybrid Candidate Multiplier",
   "agents.defaults.memorySearch.cache.enabled": "Memory Search Embedding Cache",
   "agents.defaults.memorySearch.cache.maxEntries": "Memory Search Embedding Cache Max Entries",
-  memory: "Memory",
-  "memory.backend": "Memory Backend",
-  "memory.citations": "Memory Citations Mode",
-  "memory.qmd.command": "QMD Binary",
-  "memory.qmd.includeDefaultMemory": "QMD Include Default Memory",
-  "memory.qmd.paths": "QMD Extra Paths",
-  "memory.qmd.paths.path": "QMD Path",
-  "memory.qmd.paths.pattern": "QMD Path Pattern",
-  "memory.qmd.paths.name": "QMD Path Name",
-  "memory.qmd.sessions.enabled": "QMD Session Indexing",
-  "memory.qmd.sessions.exportDir": "QMD Session Export Directory",
-  "memory.qmd.sessions.retentionDays": "QMD Session Retention (days)",
-  "memory.qmd.update.interval": "QMD Update Interval",
-  "memory.qmd.update.debounceMs": "QMD Update Debounce (ms)",
-  "memory.qmd.update.onBoot": "QMD Update on Startup",
-  "memory.qmd.update.embedInterval": "QMD Embed Interval",
-  "memory.qmd.limits.maxResults": "QMD Max Results",
-  "memory.qmd.limits.maxSnippetChars": "QMD Max Snippet Chars",
-  "memory.qmd.limits.maxInjectedChars": "QMD Max Injected Chars",
-  "memory.qmd.limits.timeoutMs": "QMD Search Timeout (ms)",
-  "memory.qmd.scope": "QMD Surface Scope",
   "auth.profiles": "Auth Profiles",
   "auth.order": "Auth Profile Order",
   "auth.cooldowns.billingBackoffHours": "Billing Backoff (hours)",
@@ -520,6 +500,8 @@ const FIELD_HELP: Record<string, string> = {
     "Vector search over MEMORY.md and memory/*.md (per-agent overrides supported).",
   "agents.defaults.memorySearch.sources":
     'Sources to index for memory search (default: ["memory"]; add "sessions" to include session transcripts).',
+  "agents.defaults.memorySearch.extraPaths":
+    "Extra paths to include in memory search (directories or .md files; relative paths resolved from workspace).",
   "agents.defaults.memorySearch.experimental.sessionMemory":
     "Enable experimental session transcript indexing for memory search (default: false).",
   "agents.defaults.memorySearch.provider": 'Embedding provider ("openai", "gemini", or "local").',
@@ -558,37 +540,6 @@ const FIELD_HELP: Record<string, string> = {
     "Multiplier for candidate pool size (default: 4).",
   "agents.defaults.memorySearch.cache.enabled":
     "Cache chunk embeddings in SQLite to speed up reindexing and frequent updates (default: true).",
-  memory: "Memory backend configuration (global).",
-  "memory.backend": 'Memory backend ("builtin" for Moltbot embeddings, "qmd" for QMD sidecar).',
-  "memory.citations": 'Default citation behavior ("auto", "on", or "off").',
-  "memory.qmd.command": "Path to the qmd binary (default: resolves from PATH).",
-  "memory.qmd.includeDefaultMemory":
-    "Whether to automatically index MEMORY.md + memory/**/*.md (default: true).",
-  "memory.qmd.paths":
-    "Additional directories/files to index with QMD (path + optional glob pattern).",
-  "memory.qmd.paths.path": "Absolute or ~-relative path to index via QMD.",
-  "memory.qmd.paths.pattern": "Glob pattern relative to the path root (default: **/*.md).",
-  "memory.qmd.paths.name":
-    "Optional stable name for the QMD collection (default derived from path).",
-  "memory.qmd.sessions.enabled":
-    "Enable QMD session transcript indexing (experimental, default: false).",
-  "memory.qmd.sessions.exportDir":
-    "Override directory for sanitized session exports before indexing.",
-  "memory.qmd.sessions.retentionDays":
-    "Retention window for exported sessions before pruning (default: unlimited).",
-  "memory.qmd.update.interval":
-    "How often the QMD sidecar refreshes indexes (duration string, default: 5m).",
-  "memory.qmd.update.debounceMs":
-    "Minimum delay between successive QMD refresh runs (default: 15000).",
-  "memory.qmd.update.onBoot": "Run QMD update once on gateway startup (default: true).",
-  "memory.qmd.update.embedInterval":
-    "How often QMD embeddings are refreshed (duration string, default: 60m). Set to 0 to disable periodic embed.",
-  "memory.qmd.limits.maxResults": "Max QMD results returned to the agent loop (default: 6).",
-  "memory.qmd.limits.maxSnippetChars": "Max characters per snippet pulled from QMD (default: 700).",
-  "memory.qmd.limits.maxInjectedChars": "Max total characters injected from QMD hits per turn.",
-  "memory.qmd.limits.timeoutMs": "Per-query timeout for QMD searches (default: 4000).",
-  "memory.qmd.scope":
-    "Session/channel scope for QMD recall (same syntax as session.sendPolicy; default: direct-only).",
   "agents.defaults.memorySearch.cache.maxEntries":
     "Optional cap on cached embeddings (best-effort).",
   "agents.defaults.memorySearch.sync.onSearch":

src/config/types.clawdbot.ts

@@ -23,7 +23,6 @@ import type { NodeHostConfig } from "./types.node-host.js";
 import type { PluginsConfig } from "./types.plugins.js";
 import type { SkillsConfig } from "./types.skills.js";
 import type { ToolsConfig } from "./types.tools.js";
-import type { MemoryConfig } from "./types.memory.js";
 
 export type MoltbotConfig = {
   meta?: {
@@ -96,7 +95,6 @@ export type MoltbotConfig = {
   canvasHost?: CanvasHostConfig;
   talk?: TalkConfig;
   gateway?: GatewayConfig;
-  memory?: MemoryConfig;
 };
 
 export type ConfigValidationIssue = {

src/config/types.memory.ts

@@ -1,46 +0,0 @@
-import type { SessionSendPolicyConfig } from "./types.base.js";
-
-export type MemoryBackend = "builtin" | "qmd";
-export type MemoryCitationsMode = "auto" | "on" | "off";
-
-export type MemoryConfig = {
-  backend?: MemoryBackend;
-  citations?: MemoryCitationsMode;
-  qmd?: MemoryQmdConfig;
-};
-
-export type MemoryQmdConfig = {
-  command?: string;
-  includeDefaultMemory?: boolean;
-  paths?: MemoryQmdIndexPath[];
-  sessions?: MemoryQmdSessionConfig;
-  update?: MemoryQmdUpdateConfig;
-  limits?: MemoryQmdLimitsConfig;
-  scope?: SessionSendPolicyConfig;
-};
-
-export type MemoryQmdIndexPath = {
-  path: string;
-  name?: string;
-  pattern?: string;
-};
-
-export type MemoryQmdSessionConfig = {
-  enabled?: boolean;
-  exportDir?: string;
-  retentionDays?: number;
-};
-
-export type MemoryQmdUpdateConfig = {
-  interval?: string;
-  debounceMs?: number;
-  onBoot?: boolean;
-  embedInterval?: string;
-};
-
-export type MemoryQmdLimitsConfig = {
-  maxResults?: number;
-  maxSnippetChars?: number;
-  maxInjectedChars?: number;
-  timeoutMs?: number;
-};

src/config/types.tools.ts

@@ -226,6 +226,8 @@ export type MemorySearchConfig = {
   enabled?: boolean;
   /** Sources to index and search (default: ["memory"]). */
   sources?: Array<"memory" | "sessions">;
+  /** Extra paths to include in memory search (directories or .md files). */
+  extraPaths?: string[];
   /** Experimental memory search settings. */
   experimental?: {
     /** Enable session transcript indexing (experimental, default: false). */

src/config/types.ts

@@ -28,4 +28,3 @@ export * from "./types.telegram.js";
 export * from "./types.tts.js";
 export * from "./types.tools.js";
 export * from "./types.whatsapp.js";
-export * from "./types.memory.js";

src/config/zod-schema.agent-runtime.ts

@@ -304,6 +304,7 @@ export const MemorySearchSchema = z
   .object({
     enabled: z.boolean().optional(),
     sources: z.array(z.union([z.literal("memory"), z.literal("sessions")])).optional(),
+    extraPaths: z.array(z.string()).optional(),
     experimental: z
       .object({
         sessionMemory: z.boolean().optional(),

src/config/zod-schema.session.ts

@@ -16,31 +16,6 @@ const SessionResetConfigSchema = z
   })
   .strict();
 
-export const SessionSendPolicySchema = z
-  .object({
-    default: z.union([z.literal("allow"), z.literal("deny")]).optional(),
-    rules: z
-      .array(
-        z
-          .object({
-            action: z.union([z.literal("allow"), z.literal("deny")]),
-            match: z
-              .object({
-                channel: z.string().optional(),
-                chatType: z
-                  .union([z.literal("direct"), z.literal("group"), z.literal("channel")])
-                  .optional(),
-                keyPrefix: z.string().optional(),
-              })
-              .strict()
-              .optional(),
-          })
-          .strict(),
-      )
-      .optional(),
-  })
-  .strict();
-
 export const SessionSchema = z
   .object({
     scope: z.union([z.literal("per-sender"), z.literal("global")]).optional(),
@@ -76,7 +51,31 @@ export const SessionSchema = z
       ])
       .optional(),
     mainKey: z.string().optional(),
-    sendPolicy: SessionSendPolicySchema.optional(),
+    sendPolicy: z
+      .object({
+        default: z.union([z.literal("allow"), z.literal("deny")]).optional(),
+        rules: z
+          .array(
+            z
+              .object({
+                action: z.union([z.literal("allow"), z.literal("deny")]),
+                match: z
+                  .object({
+                    channel: z.string().optional(),
+                    chatType: z
+                      .union([z.literal("direct"), z.literal("group"), z.literal("channel")])
+                      .optional(),
+                    keyPrefix: z.string().optional(),
+                  })
+                  .strict()
+                  .optional(),
+              })
+              .strict(),
+          )
+          .optional(),
+      })
+      .strict()
+      .optional(),
     agentToAgent: z
       .object({
         maxPingPongTurns: z.number().int().min(0).max(5).optional(),

src/config/zod-schema.ts

@@ -5,12 +5,7 @@ import { AgentsSchema, AudioSchema, BindingsSchema, BroadcastSchema } from "./zo
 import { HexColorSchema, ModelsConfigSchema } from "./zod-schema.core.js";
 import { HookMappingSchema, HooksGmailSchema, InternalHooksSchema } from "./zod-schema.hooks.js";
 import { ChannelsSchema } from "./zod-schema.providers.js";
-import {
-  CommandsSchema,
-  MessagesSchema,
-  SessionSchema,
-  SessionSendPolicySchema,
-} from "./zod-schema.session.js";
+import { CommandsSchema, MessagesSchema, SessionSchema } from "./zod-schema.session.js";
 
 const BrowserSnapshotDefaultsSchema = z
   .object({
@@ -32,61 +27,6 @@ const NodeHostSchema = z
   .strict()
   .optional();
 
-const MemoryQmdPathSchema = z
-  .object({
-    path: z.string(),
-    name: z.string().optional(),
-    pattern: z.string().optional(),
-  })
-  .strict();
-
-const MemoryQmdSessionSchema = z
-  .object({
-    enabled: z.boolean().optional(),
-    exportDir: z.string().optional(),
-    retentionDays: z.number().int().nonnegative().optional(),
-  })
-  .strict();
-
-const MemoryQmdUpdateSchema = z
-  .object({
-    interval: z.string().optional(),
-    debounceMs: z.number().int().nonnegative().optional(),
-    onBoot: z.boolean().optional(),
-    embedInterval: z.string().optional(),
-  })
-  .strict();
-
-const MemoryQmdLimitsSchema = z
-  .object({
-    maxResults: z.number().int().positive().optional(),
-    maxSnippetChars: z.number().int().positive().optional(),
-    maxInjectedChars: z.number().int().positive().optional(),
-    timeoutMs: z.number().int().nonnegative().optional(),
-  })
-  .strict();
-
-const MemoryQmdSchema = z
-  .object({
-    command: z.string().optional(),
-    includeDefaultMemory: z.boolean().optional(),
-    paths: z.array(MemoryQmdPathSchema).optional(),
-    sessions: MemoryQmdSessionSchema.optional(),
-    update: MemoryQmdUpdateSchema.optional(),
-    limits: MemoryQmdLimitsSchema.optional(),
-    scope: SessionSendPolicySchema.optional(),
-  })
-  .strict();
-
-const MemorySchema = z
-  .object({
-    backend: z.union([z.literal("builtin"), z.literal("qmd")]).optional(),
-    citations: z.union([z.literal("auto"), z.literal("on"), z.literal("off")]).optional(),
-    qmd: MemoryQmdSchema.optional(),
-  })
-  .strict()
-  .optional();
-
 export const MoltbotSchema = z
   .object({
     meta: z
@@ -505,7 +445,6 @@ export const MoltbotSchema = z
       })
       .strict()
       .optional(),
-    memory: MemorySchema,
     skills: z
       .object({
         allowBundled: z.array(z.string()).optional(),

src/discord/targets.ts

@@ -84,14 +84,10 @@ export async function resolveDiscordTarget(
 
   const likelyUsername = isLikelyUsername(trimmed);
   const shouldLookup = isExplicitUserLookup(trimmed, parseOptions) || likelyUsername;
-
-  // Parse directly if it's already a known format. Use a safe parse so ambiguous
-  // numeric targets don't throw when we still want to attempt username lookup.
   const directParse = safeParseDiscordTarget(trimmed, parseOptions);
   if (directParse && directParse.kind !== "channel" && !likelyUsername) {
     return directParse;
   }
-
   if (!shouldLookup) {
     return directParse ?? parseDiscordTarget(trimmed, parseOptions);
   }

src/hooks/bundled/session-memory/HOOK.md

@@ -23,7 +23,7 @@ Automatically saves session context to your workspace memory when you issue the
 When you run `/new` to start a fresh session:
 
 1. **Finds the previous session** - Uses the pre-reset session entry to locate the correct transcript
-2. **Extracts conversation** - Reads the last 15 lines of conversation from the session
+2. **Extracts conversation** - Reads the last N user/assistant messages from the session (default: 15, configurable)
 3. **Generates descriptive slug** - Uses LLM to create a meaningful filename slug based on conversation content
 4. **Saves to memory** - Creates a new file at `<workspace>/memory/YYYY-MM-DD-slug.md`
 5. **Sends confirmation** - Notifies you with the file path
@@ -57,7 +57,30 @@ The hook uses your configured LLM provider to generate slugs, so it works with a
 
 ## Configuration
 
-No additional configuration required. The hook automatically:
+The hook supports optional configuration:
+
+| Option     | Type   | Default | Description                                                     |
+| ---------- | ------ | ------- | --------------------------------------------------------------- |
+| `messages` | number | 15      | Number of user/assistant messages to include in the memory file |
+
+Example configuration:
+
+```json
+{
+  "hooks": {
+    "internal": {
+      "entries": {
+        "session-memory": {
+          "enabled": true,
+          "messages": 25
+        }
+      }
+    }
+  }
+}
+```
+
+The hook automatically:
 
 - Uses your workspace directory (`~/clawd` by default)
 - Uses your configured LLM for slug generation

src/hooks/bundled/session-memory/handler.test.ts

@@ -0,0 +1,379 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+import handler from "./handler.js";
+import { createHookEvent } from "../../hooks.js";
+import type { ClawdbotConfig } from "../../../config/config.js";
+import { makeTempWorkspace, writeWorkspaceFile } from "../../../test-helpers/workspace.js";
+
+/**
+ * Create a mock session JSONL file with various entry types
+ */
+function createMockSessionContent(
+  entries: Array<{ role: string; content: string } | { type: string }>,
+): string {
+  return entries
+    .map((entry) => {
+      if ("role" in entry) {
+        return JSON.stringify({
+          type: "message",
+          message: {
+            role: entry.role,
+            content: entry.content,
+          },
+        });
+      }
+      // Non-message entry (tool call, system, etc.)
+      return JSON.stringify(entry);
+    })
+    .join("\n");
+}
+
+describe("session-memory hook", () => {
+  it("skips non-command events", async () => {
+    const tempDir = await makeTempWorkspace("clawdbot-session-memory-");
+
+    const event = createHookEvent("agent", "bootstrap", "agent:main:main", {
+      workspaceDir: tempDir,
+    });
+
+    await handler(event);
+
+    // Memory directory should not be created for non-command events
+    const memoryDir = path.join(tempDir, "memory");
+    await expect(fs.access(memoryDir)).rejects.toThrow();
+  });
+
+  it("skips commands other than new", async () => {
+    const tempDir = await makeTempWorkspace("clawdbot-session-memory-");
+
+    const event = createHookEvent("command", "help", "agent:main:main", {
+      workspaceDir: tempDir,
+    });
+
+    await handler(event);
+
+    // Memory directory should not be created for other commands
+    const memoryDir = path.join(tempDir, "memory");
+    await expect(fs.access(memoryDir)).rejects.toThrow();
+  });
+
+  it("creates memory file with session content on /new command", async () => {
+    const tempDir = await makeTempWorkspace("clawdbot-session-memory-");
+    const sessionsDir = path.join(tempDir, "sessions");
+    await fs.mkdir(sessionsDir, { recursive: true });
+
+    // Create a mock session file with user/assistant messages
+    const sessionContent = createMockSessionContent([
+      { role: "user", content: "Hello there" },
+      { role: "assistant", content: "Hi! How can I help?" },
+      { role: "user", content: "What is 2+2?" },
+      { role: "assistant", content: "2+2 equals 4" },
+    ]);
+    const sessionFile = await writeWorkspaceFile({
+      dir: sessionsDir,
+      name: "test-session.jsonl",
+      content: sessionContent,
+    });
+
+    const cfg: ClawdbotConfig = {
+      agents: { defaults: { workspace: tempDir } },
+    };
+
+    const event = createHookEvent("command", "new", "agent:main:main", {
+      cfg,
+      previousSessionEntry: {
+        sessionId: "test-123",
+        sessionFile,
+      },
+    });
+
+    await handler(event);
+
+    // Memory file should be created
+    const memoryDir = path.join(tempDir, "memory");
+    const files = await fs.readdir(memoryDir);
+    expect(files.length).toBe(1);
+
+    // Read the memory file and verify content
+    const memoryContent = await fs.readFile(path.join(memoryDir, files[0]!), "utf-8");
+    expect(memoryContent).toContain("user: Hello there");
+    expect(memoryContent).toContain("assistant: Hi! How can I help?");
+    expect(memoryContent).toContain("user: What is 2+2?");
+    expect(memoryContent).toContain("assistant: 2+2 equals 4");
+  });
+
+  it("filters out non-message entries (tool calls, system)", async () => {
+    const tempDir = await makeTempWorkspace("clawdbot-session-memory-");
+    const sessionsDir = path.join(tempDir, "sessions");
+    await fs.mkdir(sessionsDir, { recursive: true });
+
+    // Create session with mixed entry types
+    const sessionContent = createMockSessionContent([
+      { role: "user", content: "Hello" },
+      { type: "tool_use", tool: "search", input: "test" },
+      { role: "assistant", content: "World" },
+      { type: "tool_result", result: "found it" },
+      { role: "user", content: "Thanks" },
+    ]);
+    const sessionFile = await writeWorkspaceFile({
+      dir: sessionsDir,
+      name: "test-session.jsonl",
+      content: sessionContent,
+    });
+
+    const cfg: ClawdbotConfig = {
+      agents: { defaults: { workspace: tempDir } },
+    };
+
+    const event = createHookEvent("command", "new", "agent:main:main", {
+      cfg,
+      previousSessionEntry: {
+        sessionId: "test-123",
+        sessionFile,
+      },
+    });
+
+    await handler(event);
+
+    const memoryDir = path.join(tempDir, "memory");
+    const files = await fs.readdir(memoryDir);
+    const memoryContent = await fs.readFile(path.join(memoryDir, files[0]!), "utf-8");
+
+    // Only user/assistant messages should be present
+    expect(memoryContent).toContain("user: Hello");
+    expect(memoryContent).toContain("assistant: World");
+    expect(memoryContent).toContain("user: Thanks");
+    // Tool entries should not appear
+    expect(memoryContent).not.toContain("tool_use");
+    expect(memoryContent).not.toContain("tool_result");
+    expect(memoryContent).not.toContain("search");
+  });
+
+  it("filters out command messages starting with /", async () => {
+    const tempDir = await makeTempWorkspace("clawdbot-session-memory-");
+    const sessionsDir = path.join(tempDir, "sessions");
+    await fs.mkdir(sessionsDir, { recursive: true });
+
+    const sessionContent = createMockSessionContent([
+      { role: "user", content: "/help" },
+      { role: "assistant", content: "Here is help info" },
+      { role: "user", content: "Normal message" },
+      { role: "user", content: "/new" },
+    ]);
+    const sessionFile = await writeWorkspaceFile({
+      dir: sessionsDir,
+      name: "test-session.jsonl",
+      content: sessionContent,
+    });
+
+    const cfg: ClawdbotConfig = {
+      agents: { defaults: { workspace: tempDir } },
+    };
+
+    const event = createHookEvent("command", "new", "agent:main:main", {
+      cfg,
+      previousSessionEntry: {
+        sessionId: "test-123",
+        sessionFile,
+      },
+    });
+
+    await handler(event);
+
+    const memoryDir = path.join(tempDir, "memory");
+    const files = await fs.readdir(memoryDir);
+    const memoryContent = await fs.readFile(path.join(memoryDir, files[0]!), "utf-8");
+
+    // Command messages should be filtered out
+    expect(memoryContent).not.toContain("/help");
+    expect(memoryContent).not.toContain("/new");
+    // Normal messages should be present
+    expect(memoryContent).toContain("assistant: Here is help info");
+    expect(memoryContent).toContain("user: Normal message");
+  });
+
+  it("respects custom messages config (limits to N messages)", async () => {
+    const tempDir = await makeTempWorkspace("clawdbot-session-memory-");
+    const sessionsDir = path.join(tempDir, "sessions");
+    await fs.mkdir(sessionsDir, { recursive: true });
+
+    // Create 10 messages
+    const entries = [];
+    for (let i = 1; i <= 10; i++) {
+      entries.push({ role: "user", content: `Message ${i}` });
+    }
+    const sessionContent = createMockSessionContent(entries);
+    const sessionFile = await writeWorkspaceFile({
+      dir: sessionsDir,
+      name: "test-session.jsonl",
+      content: sessionContent,
+    });
+
+    // Configure to only include last 3 messages
+    const cfg: ClawdbotConfig = {
+      agents: { defaults: { workspace: tempDir } },
+      hooks: {
+        internal: {
+          entries: {
+            "session-memory": { enabled: true, messages: 3 },
+          },
+        },
+      },
+    };
+
+    const event = createHookEvent("command", "new", "agent:main:main", {
+      cfg,
+      previousSessionEntry: {
+        sessionId: "test-123",
+        sessionFile,
+      },
+    });
+
+    await handler(event);
+
+    const memoryDir = path.join(tempDir, "memory");
+    const files = await fs.readdir(memoryDir);
+    const memoryContent = await fs.readFile(path.join(memoryDir, files[0]!), "utf-8");
+
+    // Only last 3 messages should be present
+    expect(memoryContent).not.toContain("user: Message 1\n");
+    expect(memoryContent).not.toContain("user: Message 7\n");
+    expect(memoryContent).toContain("user: Message 8");
+    expect(memoryContent).toContain("user: Message 9");
+    expect(memoryContent).toContain("user: Message 10");
+  });
+
+  it("filters messages before slicing (fix for #2681)", async () => {
+    const tempDir = await makeTempWorkspace("clawdbot-session-memory-");
+    const sessionsDir = path.join(tempDir, "sessions");
+    await fs.mkdir(sessionsDir, { recursive: true });
+
+    // Create session with many tool entries interspersed with messages
+    // This tests that we filter FIRST, then slice - not the other way around
+    const entries = [
+      { role: "user", content: "First message" },
+      { type: "tool_use", tool: "test1" },
+      { type: "tool_result", result: "result1" },
+      { role: "assistant", content: "Second message" },
+      { type: "tool_use", tool: "test2" },
+      { type: "tool_result", result: "result2" },
+      { role: "user", content: "Third message" },
+      { type: "tool_use", tool: "test3" },
+      { type: "tool_result", result: "result3" },
+      { role: "assistant", content: "Fourth message" },
+    ];
+    const sessionContent = createMockSessionContent(entries);
+    const sessionFile = await writeWorkspaceFile({
+      dir: sessionsDir,
+      name: "test-session.jsonl",
+      content: sessionContent,
+    });
+
+    // Request 3 messages - if we sliced first, we'd only get 1-2 messages
+    // because the last 3 lines include tool entries
+    const cfg: ClawdbotConfig = {
+      agents: { defaults: { workspace: tempDir } },
+      hooks: {
+        internal: {
+          entries: {
+            "session-memory": { enabled: true, messages: 3 },
+          },
+        },
+      },
+    };
+
+    const event = createHookEvent("command", "new", "agent:main:main", {
+      cfg,
+      previousSessionEntry: {
+        sessionId: "test-123",
+        sessionFile,
+      },
+    });
+
+    await handler(event);
+
+    const memoryDir = path.join(tempDir, "memory");
+    const files = await fs.readdir(memoryDir);
+    const memoryContent = await fs.readFile(path.join(memoryDir, files[0]!), "utf-8");
+
+    // Should have exactly 3 user/assistant messages (the last 3)
+    expect(memoryContent).not.toContain("First message");
+    expect(memoryContent).toContain("user: Third message");
+    expect(memoryContent).toContain("assistant: Second message");
+    expect(memoryContent).toContain("assistant: Fourth message");
+  });
+
+  it("handles empty session files gracefully", async () => {
+    const tempDir = await makeTempWorkspace("clawdbot-session-memory-");
+    const sessionsDir = path.join(tempDir, "sessions");
+    await fs.mkdir(sessionsDir, { recursive: true });
+
+    const sessionFile = await writeWorkspaceFile({
+      dir: sessionsDir,
+      name: "test-session.jsonl",
+      content: "",
+    });
+
+    const cfg: ClawdbotConfig = {
+      agents: { defaults: { workspace: tempDir } },
+    };
+
+    const event = createHookEvent("command", "new", "agent:main:main", {
+      cfg,
+      previousSessionEntry: {
+        sessionId: "test-123",
+        sessionFile,
+      },
+    });
+
+    // Should not throw
+    await handler(event);
+
+    // Memory file should still be created with metadata
+    const memoryDir = path.join(tempDir, "memory");
+    const files = await fs.readdir(memoryDir);
+    expect(files.length).toBe(1);
+  });
+
+  it("handles session files with fewer messages than requested", async () => {
+    const tempDir = await makeTempWorkspace("clawdbot-session-memory-");
+    const sessionsDir = path.join(tempDir, "sessions");
+    await fs.mkdir(sessionsDir, { recursive: true });
+
+    // Only 2 messages but requesting 15 (default)
+    const sessionContent = createMockSessionContent([
+      { role: "user", content: "Only message 1" },
+      { role: "assistant", content: "Only message 2" },
+    ]);
+    const sessionFile = await writeWorkspaceFile({
+      dir: sessionsDir,
+      name: "test-session.jsonl",
+      content: sessionContent,
+    });
+
+    const cfg: ClawdbotConfig = {
+      agents: { defaults: { workspace: tempDir } },
+    };
+
+    const event = createHookEvent("command", "new", "agent:main:main", {
+      cfg,
+      previousSessionEntry: {
+        sessionId: "test-123",
+        sessionFile,
+      },
+    });
+
+    await handler(event);
+
+    const memoryDir = path.join(tempDir, "memory");
+    const files = await fs.readdir(memoryDir);
+    const memoryContent = await fs.readFile(path.join(memoryDir, files[0]!), "utf-8");
+
+    // Both messages should be included
+    expect(memoryContent).toContain("user: Only message 1");
+    expect(memoryContent).toContain("assistant: Only message 2");
+  });
+});

src/hooks/bundled/session-memory/handler.ts

@@ -8,25 +8,27 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import os from "node:os";
+import { fileURLToPath } from "node:url";
 import type { MoltbotConfig } from "../../../config/config.js";
 import { resolveAgentWorkspaceDir } from "../../../agents/agent-scope.js";
 import { resolveAgentIdFromSessionKey } from "../../../routing/session-key.js";
+import { resolveHookConfig } from "../../config.js";
 import type { HookHandler } from "../../hooks.js";
 
 /**
  * Read recent messages from session file for slug generation
  */
-async function getRecentSessionContent(sessionFilePath: string): Promise<string | null> {
+async function getRecentSessionContent(
+  sessionFilePath: string,
+  messageCount: number = 15,
+): Promise<string | null> {
   try {
     const content = await fs.readFile(sessionFilePath, "utf-8");
     const lines = content.trim().split("\n");
 
-    // Get last 15 lines (recent conversation)
-    const recentLines = lines.slice(-15);
-
-    // Parse JSONL and extract messages
-    const messages: string[] = [];
-    for (const line of recentLines) {
+    // Parse JSONL and extract user/assistant messages first
+    const allMessages: string[] = [];
+    for (const line of lines) {
       try {
         const entry = JSON.parse(line);
         // Session files have entries with type="message" containing a nested message object
@@ -39,7 +41,7 @@ async function getRecentSessionContent(sessionFilePath: string): Promise<string
               ? msg.content.find((c: any) => c.type === "text")?.text
               : msg.content;
             if (text && !text.startsWith("/")) {
-              messages.push(`${role}: ${text}`);
+              allMessages.push(`${role}: ${text}`);
             }
           }
         }
@@ -48,7 +50,9 @@ async function getRecentSessionContent(sessionFilePath: string): Promise<string
       }
     }
 
-    return messages.join("\n");
+    // Then slice to get exactly messageCount messages
+    const recentMessages = allMessages.slice(-messageCount);
+    return recentMessages.join("\n");
   } catch {
     return null;
   }
@@ -93,12 +97,19 @@ const saveSessionToMemory: HookHandler = async (event) => {
 
     const sessionFile = currentSessionFile || undefined;
 
+    // Read message count from hook config (default: 15)
+    const hookConfig = resolveHookConfig(cfg, "session-memory");
+    const messageCount =
+      typeof hookConfig?.messages === "number" && hookConfig.messages > 0
+        ? hookConfig.messages
+        : 15;
+
     let slug: string | null = null;
     let sessionContent: string | null = null;
 
     if (sessionFile) {
       // Get recent conversation content
-      sessionContent = await getRecentSessionContent(sessionFile);
+      sessionContent = await getRecentSessionContent(sessionFile, messageCount);
       console.log("[session-memory] sessionContent length:", sessionContent?.length || 0);
 
       if (sessionContent && cfg) {
@@ -106,10 +117,7 @@ const saveSessionToMemory: HookHandler = async (event) => {
         // Dynamically import the LLM slug generator (avoids module caching issues)
         // When compiled, handler is at dist/hooks/bundled/session-memory/handler.js
         // Going up ../.. puts us at dist/hooks/, so just add llm-slug-generator.js
-        const moltbotRoot = path.resolve(
-          path.dirname(import.meta.url.replace("file://", "")),
-          "../..",
-        );
+        const moltbotRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
         const slugGenPath = path.join(moltbotRoot, "llm-slug-generator.js");
         const { generateSlugViaLLM } = await import(slugGenPath);
 

src/media-understanding/apply.test.ts

@@ -41,7 +41,7 @@ describe("applyMediaUnderstanding", () => {
     mockedResolveApiKey.mockClear();
     mockedFetchRemoteMedia.mockReset();
     mockedFetchRemoteMedia.mockResolvedValue({
-      buffer: Buffer.from("audio-bytes"),
+      buffer: Buffer.from([0, 255, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]),
       contentType: "audio/ogg",
       fileName: "note.ogg",
     });
@@ -51,7 +51,7 @@ describe("applyMediaUnderstanding", () => {
     const { applyMediaUnderstanding } = await loadApply();
     const dir = await fs.mkdtemp(path.join(os.tmpdir(), "moltbot-media-"));
     const audioPath = path.join(dir, "note.ogg");
-    await fs.writeFile(audioPath, "hello");
+    await fs.writeFile(audioPath, Buffer.from([0, 255, 0, 1, 2, 3, 4, 5, 6, 7, 8]));
 
     const ctx: MsgContext = {
       Body: "<media:audio>",
@@ -94,7 +94,7 @@ describe("applyMediaUnderstanding", () => {
     const { applyMediaUnderstanding } = await loadApply();
     const dir = await fs.mkdtemp(path.join(os.tmpdir(), "moltbot-media-"));
     const audioPath = path.join(dir, "note.ogg");
-    await fs.writeFile(audioPath, "hello");
+    await fs.writeFile(audioPath, Buffer.from([0, 255, 0, 1, 2, 3, 4, 5, 6, 7, 8]));
 
     const ctx: MsgContext = {
       Body: "<media:audio> /capture status",
@@ -176,7 +176,7 @@ describe("applyMediaUnderstanding", () => {
     const { applyMediaUnderstanding } = await loadApply();
     const dir = await fs.mkdtemp(path.join(os.tmpdir(), "moltbot-media-"));
     const audioPath = path.join(dir, "large.wav");
-    await fs.writeFile(audioPath, "0123456789");
+    await fs.writeFile(audioPath, Buffer.from([0, 255, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]));
 
     const ctx: MsgContext = {
       Body: "<media:audio>",
@@ -211,7 +211,7 @@ describe("applyMediaUnderstanding", () => {
     const { applyMediaUnderstanding } = await loadApply();
     const dir = await fs.mkdtemp(path.join(os.tmpdir(), "moltbot-media-"));
     const audioPath = path.join(dir, "note.ogg");
-    await fs.writeFile(audioPath, "hello");
+    await fs.writeFile(audioPath, Buffer.from([0, 255, 0, 1, 2, 3, 4, 5, 6, 7, 8]));
 
     const ctx: MsgContext = {
       Body: "<media:audio>",
@@ -352,7 +352,7 @@ describe("applyMediaUnderstanding", () => {
     const { applyMediaUnderstanding } = await loadApply();
     const dir = await fs.mkdtemp(path.join(os.tmpdir(), "moltbot-media-"));
     const audioPath = path.join(dir, "fallback.ogg");
-    await fs.writeFile(audioPath, "hello");
+    await fs.writeFile(audioPath, Buffer.from([0, 255, 0, 1, 2, 3, 4, 5, 6]));
 
     const ctx: MsgContext = {
       Body: "<media:audio>",
@@ -390,8 +390,8 @@ describe("applyMediaUnderstanding", () => {
     const dir = await fs.mkdtemp(path.join(os.tmpdir(), "moltbot-media-"));
     const audioPathA = path.join(dir, "note-a.ogg");
     const audioPathB = path.join(dir, "note-b.ogg");
-    await fs.writeFile(audioPathA, "hello");
-    await fs.writeFile(audioPathB, "world");
+    await fs.writeFile(audioPathA, Buffer.from([200, 201, 202, 203, 204, 205, 206, 207, 208]));
+    await fs.writeFile(audioPathB, Buffer.from([200, 201, 202, 203, 204, 205, 206, 207, 208]));
 
     const ctx: MsgContext = {
       Body: "<media:audio>",
@@ -435,7 +435,7 @@ describe("applyMediaUnderstanding", () => {
     const audioPath = path.join(dir, "note.ogg");
     const videoPath = path.join(dir, "clip.mp4");
     await fs.writeFile(imagePath, "image-bytes");
-    await fs.writeFile(audioPath, "audio-bytes");
+    await fs.writeFile(audioPath, Buffer.from([200, 201, 202, 203, 204, 205, 206, 207, 208]));
     await fs.writeFile(videoPath, "video-bytes");
 
     const ctx: MsgContext = {
@@ -487,4 +487,187 @@ describe("applyMediaUnderstanding", () => {
     expect(ctx.CommandBody).toBe("audio ok");
     expect(ctx.BodyForCommands).toBe("audio ok");
   });
+
+  it("treats text-like audio attachments as CSV (comma wins over tabs)", async () => {
+    const { applyMediaUnderstanding } = await loadApply();
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "moltbot-media-"));
+    const csvPath = path.join(dir, "data.mp3");
+    const csvText = '"a","b"\t"c"\n"1","2"\t"3"';
+    const csvBuffer = Buffer.concat([Buffer.from([0xff, 0xfe]), Buffer.from(csvText, "utf16le")]);
+    await fs.writeFile(csvPath, csvBuffer);
+
+    const ctx: MsgContext = {
+      Body: "<media:audio>",
+      MediaPath: csvPath,
+      MediaType: "audio/mpeg",
+    };
+    const cfg: MoltbotConfig = {
+      tools: {
+        media: {
+          audio: { enabled: false },
+          image: { enabled: false },
+          video: { enabled: false },
+        },
+      },
+    };
+
+    const result = await applyMediaUnderstanding({ ctx, cfg });
+
+    expect(result.appliedFile).toBe(true);
+    expect(ctx.Body).toContain('<file name="data.mp3" mime="text/csv">');
+    expect(ctx.Body).toContain('"a","b"\t"c"');
+  });
+
+  it("infers TSV when tabs are present without commas", async () => {
+    const { applyMediaUnderstanding } = await loadApply();
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "moltbot-media-"));
+    const tsvPath = path.join(dir, "report.mp3");
+    const tsvText = "a\tb\tc\n1\t2\t3";
+    await fs.writeFile(tsvPath, tsvText);
+
+    const ctx: MsgContext = {
+      Body: "<media:audio>",
+      MediaPath: tsvPath,
+      MediaType: "audio/mpeg",
+    };
+    const cfg: MoltbotConfig = {
+      tools: {
+        media: {
+          audio: { enabled: false },
+          image: { enabled: false },
+          video: { enabled: false },
+        },
+      },
+    };
+
+    const result = await applyMediaUnderstanding({ ctx, cfg });
+
+    expect(result.appliedFile).toBe(true);
+    expect(ctx.Body).toContain('<file name="report.mp3" mime="text/tab-separated-values">');
+    expect(ctx.Body).toContain("a\tb\tc");
+  });
+
+  it("escapes XML special characters in filenames to prevent injection", async () => {
+    const { applyMediaUnderstanding } = await loadApply();
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "moltbot-media-"));
+    // Create file with XML special characters in the name (what filesystem allows)
+    // Note: The sanitizeFilename in store.ts would strip most dangerous chars,
+    // but we test that even if some slip through, they get escaped in output
+    const filePath = path.join(dir, "file<test>.txt");
+    await fs.writeFile(filePath, "safe content");
+
+    const ctx: MsgContext = {
+      Body: "<media:document>",
+      MediaPath: filePath,
+      MediaType: "text/plain",
+    };
+    const cfg: MoltbotConfig = {
+      tools: {
+        media: {
+          audio: { enabled: false },
+          image: { enabled: false },
+          video: { enabled: false },
+        },
+      },
+    };
+
+    const result = await applyMediaUnderstanding({ ctx, cfg });
+
+    expect(result.appliedFile).toBe(true);
+    // Verify XML special chars are escaped in the output
+    expect(ctx.Body).toContain("&lt;");
+    expect(ctx.Body).toContain("&gt;");
+    // The raw < and > should not appear unescaped in the name attribute
+    expect(ctx.Body).not.toMatch(/name="[^"]*<[^"]*"/);
+  });
+
+  it("normalizes MIME types to prevent attribute injection", async () => {
+    const { applyMediaUnderstanding } = await loadApply();
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "moltbot-media-"));
+    const filePath = path.join(dir, "data.txt");
+    await fs.writeFile(filePath, "test content");
+
+    const ctx: MsgContext = {
+      Body: "<media:document>",
+      MediaPath: filePath,
+      // Attempt to inject via MIME type with quotes - normalization should strip this
+      MediaType: 'text/plain" onclick="alert(1)',
+    };
+    const cfg: MoltbotConfig = {
+      tools: {
+        media: {
+          audio: { enabled: false },
+          image: { enabled: false },
+          video: { enabled: false },
+        },
+      },
+    };
+
+    const result = await applyMediaUnderstanding({ ctx, cfg });
+
+    expect(result.appliedFile).toBe(true);
+    // MIME normalization strips everything after first ; or " - verify injection is blocked
+    expect(ctx.Body).not.toContain("onclick=");
+    expect(ctx.Body).not.toContain("alert(1)");
+    // Verify the MIME type is normalized to just "text/plain"
+    expect(ctx.Body).toContain('mime="text/plain"');
+  });
+
+  it("handles path traversal attempts in filenames safely", async () => {
+    const { applyMediaUnderstanding } = await loadApply();
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "moltbot-media-"));
+    // Even if a file somehow got a path-like name, it should be handled safely
+    const filePath = path.join(dir, "normal.txt");
+    await fs.writeFile(filePath, "legitimate content");
+
+    const ctx: MsgContext = {
+      Body: "<media:document>",
+      MediaPath: filePath,
+      MediaType: "text/plain",
+    };
+    const cfg: MoltbotConfig = {
+      tools: {
+        media: {
+          audio: { enabled: false },
+          image: { enabled: false },
+          video: { enabled: false },
+        },
+      },
+    };
+
+    const result = await applyMediaUnderstanding({ ctx, cfg });
+
+    expect(result.appliedFile).toBe(true);
+    // Verify the file was processed and output contains expected structure
+    expect(ctx.Body).toContain('<file name="');
+    expect(ctx.Body).toContain('mime="text/plain"');
+    expect(ctx.Body).toContain("legitimate content");
+  });
+
+  it("handles files with non-ASCII Unicode filenames", async () => {
+    const { applyMediaUnderstanding } = await loadApply();
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "moltbot-media-"));
+    const filePath = path.join(dir, "文档.txt");
+    await fs.writeFile(filePath, "中文内容");
+
+    const ctx: MsgContext = {
+      Body: "<media:document>",
+      MediaPath: filePath,
+      MediaType: "text/plain",
+    };
+    const cfg: MoltbotConfig = {
+      tools: {
+        media: {
+          audio: { enabled: false },
+          image: { enabled: false },
+          video: { enabled: false },
+        },
+      },
+    };
+
+    const result = await applyMediaUnderstanding({ ctx, cfg });
+
+    expect(result.appliedFile).toBe(true);
+    expect(ctx.Body).toContain("中文内容");
+  });
 });

src/media-understanding/apply.ts

@@ -1,6 +1,22 @@
+import path from "node:path";
+
 import type { MoltbotConfig } from "../config/config.js";
 import type { MsgContext } from "../auto-reply/templating.js";
 import { finalizeInboundContext } from "../auto-reply/reply/inbound-context.js";
+import { logVerbose, shouldLogVerbose } from "../globals.js";
+import {
+  DEFAULT_INPUT_FILE_MAX_BYTES,
+  DEFAULT_INPUT_FILE_MAX_CHARS,
+  DEFAULT_INPUT_FILE_MIMES,
+  DEFAULT_INPUT_MAX_REDIRECTS,
+  DEFAULT_INPUT_PDF_MAX_PAGES,
+  DEFAULT_INPUT_PDF_MAX_PIXELS,
+  DEFAULT_INPUT_PDF_MIN_TEXT_CHARS,
+  DEFAULT_INPUT_TIMEOUT_MS,
+  extractFileContentFromSource,
+  normalizeMimeList,
+  normalizeMimeType,
+} from "../media/input-files.js";
 import {
   extractMediaUserText,
   formatAudioTranscripts,
@@ -14,6 +30,7 @@ import type {
 } from "./types.js";
 import { runWithConcurrency } from "./concurrency.js";
 import { resolveConcurrency } from "./resolve.js";
+import { resolveAttachmentKind } from "./attachments.js";
 import {
   type ActiveMediaModel,
   buildProviderRegistry,
@@ -28,9 +45,279 @@ export type ApplyMediaUnderstandingResult = {
   appliedImage: boolean;
   appliedAudio: boolean;
   appliedVideo: boolean;
+  appliedFile: boolean;
 };
 
 const CAPABILITY_ORDER: MediaUnderstandingCapability[] = ["image", "audio", "video"];
+const EXTRA_TEXT_MIMES = [
+  "application/xml",
+  "text/xml",
+  "application/x-yaml",
+  "text/yaml",
+  "application/yaml",
+  "application/javascript",
+  "text/javascript",
+  "text/tab-separated-values",
+];
+const TEXT_EXT_MIME = new Map<string, string>([
+  [".csv", "text/csv"],
+  [".tsv", "text/tab-separated-values"],
+  [".txt", "text/plain"],
+  [".md", "text/markdown"],
+  [".log", "text/plain"],
+  [".ini", "text/plain"],
+  [".cfg", "text/plain"],
+  [".conf", "text/plain"],
+  [".env", "text/plain"],
+  [".json", "application/json"],
+  [".yaml", "text/yaml"],
+  [".yml", "text/yaml"],
+  [".xml", "application/xml"],
+]);
+
+const XML_ESCAPE_MAP: Record<string, string> = {
+  "<": "&lt;",
+  ">": "&gt;",
+  "&": "&amp;",
+  '"': "&quot;",
+  "'": "&apos;",
+};
+
+/**
+ * Escapes special XML characters in attribute values to prevent injection.
+ */
+function xmlEscapeAttr(value: string): string {
+  return value.replace(/[<>&"']/g, (char) => XML_ESCAPE_MAP[char] ?? char);
+}
+
+function resolveFileLimits(cfg: MoltbotConfig) {
+  const files = cfg.gateway?.http?.endpoints?.responses?.files;
+  return {
+    allowUrl: files?.allowUrl ?? true,
+    allowedMimes: normalizeMimeList(files?.allowedMimes, DEFAULT_INPUT_FILE_MIMES),
+    maxBytes: files?.maxBytes ?? DEFAULT_INPUT_FILE_MAX_BYTES,
+    maxChars: files?.maxChars ?? DEFAULT_INPUT_FILE_MAX_CHARS,
+    maxRedirects: files?.maxRedirects ?? DEFAULT_INPUT_MAX_REDIRECTS,
+    timeoutMs: files?.timeoutMs ?? DEFAULT_INPUT_TIMEOUT_MS,
+    pdf: {
+      maxPages: files?.pdf?.maxPages ?? DEFAULT_INPUT_PDF_MAX_PAGES,
+      maxPixels: files?.pdf?.maxPixels ?? DEFAULT_INPUT_PDF_MAX_PIXELS,
+      minTextChars: files?.pdf?.minTextChars ?? DEFAULT_INPUT_PDF_MIN_TEXT_CHARS,
+    },
+  };
+}
+
+function appendFileBlocks(body: string | undefined, blocks: string[]): string {
+  if (!blocks || blocks.length === 0) {
+    return body ?? "";
+  }
+  const base = typeof body === "string" ? body.trim() : "";
+  const suffix = blocks.join("\n\n").trim();
+  if (!base) {
+    return suffix;
+  }
+  return `${base}\n\n${suffix}`.trim();
+}
+
+function resolveUtf16Charset(buffer?: Buffer): "utf-16le" | "utf-16be" | undefined {
+  if (!buffer || buffer.length < 2) return undefined;
+  const b0 = buffer[0];
+  const b1 = buffer[1];
+  if (b0 === 0xff && b1 === 0xfe) {
+    return "utf-16le";
+  }
+  if (b0 === 0xfe && b1 === 0xff) {
+    return "utf-16be";
+  }
+  const sampleLen = Math.min(buffer.length, 2048);
+  let zeroCount = 0;
+  for (let i = 0; i < sampleLen; i += 1) {
+    if (buffer[i] === 0) zeroCount += 1;
+  }
+  if (zeroCount / sampleLen > 0.2) {
+    return "utf-16le";
+  }
+  return undefined;
+}
+
+function looksLikeUtf8Text(buffer?: Buffer): boolean {
+  if (!buffer || buffer.length === 0) return false;
+  const sampleLen = Math.min(buffer.length, 4096);
+  let printable = 0;
+  let other = 0;
+  for (let i = 0; i < sampleLen; i += 1) {
+    const byte = buffer[i];
+    if (byte === 0) {
+      other += 1;
+      continue;
+    }
+    if (byte === 9 || byte === 10 || byte === 13 || (byte >= 32 && byte <= 126)) {
+      printable += 1;
+    } else {
+      other += 1;
+    }
+  }
+  const total = printable + other;
+  if (total === 0) return false;
+  return printable / total > 0.85;
+}
+
+function decodeTextSample(buffer?: Buffer): string {
+  if (!buffer || buffer.length === 0) return "";
+  const sample = buffer.subarray(0, Math.min(buffer.length, 8192));
+  const utf16Charset = resolveUtf16Charset(sample);
+  if (utf16Charset === "utf-16be") {
+    const swapped = Buffer.alloc(sample.length);
+    for (let i = 0; i + 1 < sample.length; i += 2) {
+      swapped[i] = sample[i + 1];
+      swapped[i + 1] = sample[i];
+    }
+    return new TextDecoder("utf-16le").decode(swapped);
+  }
+  if (utf16Charset === "utf-16le") {
+    return new TextDecoder("utf-16le").decode(sample);
+  }
+  return new TextDecoder("utf-8").decode(sample);
+}
+
+function guessDelimitedMime(text: string): string | undefined {
+  if (!text) return undefined;
+  const line = text.split(/\r?\n/)[0] ?? "";
+  const tabs = (line.match(/\t/g) ?? []).length;
+  const commas = (line.match(/,/g) ?? []).length;
+  if (commas > 0) {
+    return "text/csv";
+  }
+  if (tabs > 0) {
+    return "text/tab-separated-values";
+  }
+  return undefined;
+}
+
+function resolveTextMimeFromName(name?: string): string | undefined {
+  if (!name) return undefined;
+  const ext = path.extname(name).toLowerCase();
+  return TEXT_EXT_MIME.get(ext);
+}
+
+async function extractFileBlocks(params: {
+  attachments: ReturnType<typeof normalizeMediaAttachments>;
+  cache: ReturnType<typeof createMediaAttachmentCache>;
+  limits: ReturnType<typeof resolveFileLimits>;
+}): Promise<string[]> {
+  const { attachments, cache, limits } = params;
+  if (!attachments || attachments.length === 0) {
+    return [];
+  }
+  const blocks: string[] = [];
+  for (const attachment of attachments) {
+    if (!attachment) {
+      continue;
+    }
+    const forcedTextMime = resolveTextMimeFromName(attachment.path ?? attachment.url ?? "");
+    const kind = forcedTextMime ? "document" : resolveAttachmentKind(attachment);
+    if (!forcedTextMime && (kind === "image" || kind === "video")) {
+      continue;
+    }
+    if (!limits.allowUrl && attachment.url && !attachment.path) {
+      if (shouldLogVerbose()) {
+        logVerbose(`media: file attachment skipped (url disabled) index=${attachment.index}`);
+      }
+      continue;
+    }
+    let bufferResult: Awaited<ReturnType<typeof cache.getBuffer>>;
+    try {
+      bufferResult = await cache.getBuffer({
+        attachmentIndex: attachment.index,
+        maxBytes: limits.maxBytes,
+        timeoutMs: limits.timeoutMs,
+      });
+    } catch (err) {
+      if (shouldLogVerbose()) {
+        logVerbose(`media: file attachment skipped (buffer): ${String(err)}`);
+      }
+      continue;
+    }
+    const nameHint = bufferResult?.fileName ?? attachment.path ?? attachment.url;
+    const forcedTextMimeResolved = forcedTextMime ?? resolveTextMimeFromName(nameHint ?? "");
+    const utf16Charset = resolveUtf16Charset(bufferResult?.buffer);
+    const textSample = decodeTextSample(bufferResult?.buffer);
+    const textLike = Boolean(utf16Charset) || looksLikeUtf8Text(bufferResult?.buffer);
+    if (!forcedTextMimeResolved && kind === "audio" && !textLike) {
+      continue;
+    }
+    const guessedDelimited = textLike ? guessDelimitedMime(textSample) : undefined;
+    const textHint =
+      forcedTextMimeResolved ?? guessedDelimited ?? (textLike ? "text/plain" : undefined);
+    const rawMime = bufferResult?.mime ?? attachment.mime;
+    const mimeType = textHint ?? normalizeMimeType(rawMime);
+    // Log when MIME type is overridden from non-text to text for auditability
+    if (textHint && rawMime && !rawMime.startsWith("text/")) {
+      logVerbose(
+        `media: MIME override from "${rawMime}" to "${textHint}" for index=${attachment.index}`,
+      );
+    }
+    if (!mimeType) {
+      if (shouldLogVerbose()) {
+        logVerbose(`media: file attachment skipped (unknown mime) index=${attachment.index}`);
+      }
+      continue;
+    }
+    const allowedMimes = new Set(limits.allowedMimes);
+    for (const extra of EXTRA_TEXT_MIMES) {
+      allowedMimes.add(extra);
+    }
+    if (mimeType.startsWith("text/")) {
+      allowedMimes.add(mimeType);
+    }
+    if (!allowedMimes.has(mimeType)) {
+      if (shouldLogVerbose()) {
+        logVerbose(
+          `media: file attachment skipped (unsupported mime ${mimeType}) index=${attachment.index}`,
+        );
+      }
+      continue;
+    }
+    let extracted: Awaited<ReturnType<typeof extractFileContentFromSource>>;
+    try {
+      const mediaType = utf16Charset ? `${mimeType}; charset=${utf16Charset}` : mimeType;
+      extracted = await extractFileContentFromSource({
+        source: {
+          type: "base64",
+          data: bufferResult.buffer.toString("base64"),
+          mediaType,
+          filename: bufferResult.fileName,
+        },
+        limits: {
+          ...limits,
+          allowedMimes,
+        },
+      });
+    } catch (err) {
+      if (shouldLogVerbose()) {
+        logVerbose(`media: file attachment skipped (extract): ${String(err)}`);
+      }
+      continue;
+    }
+    const text = extracted?.text?.trim() ?? "";
+    let blockText = text;
+    if (!blockText) {
+      if (extracted?.images && extracted.images.length > 0) {
+        blockText = "[PDF content rendered to images; images not forwarded to model]";
+      } else {
+        blockText = "[No extractable text]";
+      }
+    }
+    const safeName = (bufferResult.fileName ?? `file-${attachment.index + 1}`)
+      .replace(/[\r\n\t]+/g, " ")
+      .trim();
+    // Escape XML special characters in attributes to prevent injection
+    blocks.push(
+      `<file name="${xmlEscapeAttr(safeName)}" mime="${xmlEscapeAttr(mimeType)}">\n${blockText}\n</file>`,
+    );
+  }
+  return blocks;
+}
 
 export async function applyMediaUnderstanding(params: {
   ctx: MsgContext;
@@ -51,6 +338,12 @@ export async function applyMediaUnderstanding(params: {
   const cache = createMediaAttachmentCache(attachments);
 
   try {
+    const fileBlocks = await extractFileBlocks({
+      attachments,
+      cache,
+      limits: resolveFileLimits(cfg),
+    });
+
     const tasks = CAPABILITY_ORDER.map((capability) => async () => {
       const config = cfg.tools?.media?.[capability];
       return await runCapability({
@@ -99,7 +392,15 @@ export async function applyMediaUnderstanding(params: {
         ctx.RawBody = originalUserText;
       }
       ctx.MediaUnderstanding = [...(ctx.MediaUnderstanding ?? []), ...outputs];
-      finalizeInboundContext(ctx, { forceBodyForAgent: true, forceBodyForCommands: true });
+    }
+    if (fileBlocks.length > 0) {
+      ctx.Body = appendFileBlocks(ctx.Body, fileBlocks);
+    }
+    if (outputs.length > 0 || fileBlocks.length > 0) {
+      finalizeInboundContext(ctx, {
+        forceBodyForAgent: true,
+        forceBodyForCommands: outputs.length > 0,
+      });
     }
 
     return {
@@ -108,6 +409,7 @@ export async function applyMediaUnderstanding(params: {
       appliedImage: outputs.some((output) => output.kind === "image.description"),
       appliedAudio: outputs.some((output) => output.kind === "audio.transcription"),
       appliedVideo: outputs.some((output) => output.kind === "video.description"),
+      appliedFile: fileBlocks.length > 0,
     };
   } finally {
     await cache.cleanup();

src/media/mime.test.ts

@@ -1,7 +1,7 @@
 import JSZip from "jszip";
 import { describe, expect, it } from "vitest";
 
-import { detectMime, imageMimeFromFormat } from "./mime.js";
+import { detectMime, extensionForMime, imageMimeFromFormat } from "./mime.js";
 
 async function makeOoxmlZip(opts: { mainMime: string; partPath: string }): Promise<Buffer> {
   const zip = new JSZip();
@@ -53,3 +53,47 @@ describe("mime detection", () => {
     expect(mime).toBe("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet");
   });
 });
+
+describe("extensionForMime", () => {
+  it("maps image MIME types to extensions", () => {
+    expect(extensionForMime("image/jpeg")).toBe(".jpg");
+    expect(extensionForMime("image/png")).toBe(".png");
+    expect(extensionForMime("image/webp")).toBe(".webp");
+    expect(extensionForMime("image/gif")).toBe(".gif");
+    expect(extensionForMime("image/heic")).toBe(".heic");
+  });
+
+  it("maps audio MIME types to extensions", () => {
+    expect(extensionForMime("audio/mpeg")).toBe(".mp3");
+    expect(extensionForMime("audio/ogg")).toBe(".ogg");
+    expect(extensionForMime("audio/x-m4a")).toBe(".m4a");
+    expect(extensionForMime("audio/mp4")).toBe(".m4a");
+  });
+
+  it("maps video MIME types to extensions", () => {
+    expect(extensionForMime("video/mp4")).toBe(".mp4");
+    expect(extensionForMime("video/quicktime")).toBe(".mov");
+  });
+
+  it("maps document MIME types to extensions", () => {
+    expect(extensionForMime("application/pdf")).toBe(".pdf");
+    expect(extensionForMime("text/plain")).toBe(".txt");
+    expect(extensionForMime("text/markdown")).toBe(".md");
+  });
+
+  it("handles case insensitivity", () => {
+    expect(extensionForMime("IMAGE/JPEG")).toBe(".jpg");
+    expect(extensionForMime("Audio/X-M4A")).toBe(".m4a");
+    expect(extensionForMime("Video/QuickTime")).toBe(".mov");
+  });
+
+  it("returns undefined for unknown MIME types", () => {
+    expect(extensionForMime("video/unknown")).toBeUndefined();
+    expect(extensionForMime("application/x-custom")).toBeUndefined();
+  });
+
+  it("returns undefined for null or undefined input", () => {
+    expect(extensionForMime(null)).toBeUndefined();
+    expect(extensionForMime(undefined)).toBeUndefined();
+  });
+});

src/media/mime.ts

@@ -13,7 +13,10 @@ const EXT_BY_MIME: Record<string, string> = {
   "image/gif": ".gif",
   "audio/ogg": ".ogg",
   "audio/mpeg": ".mp3",
+  "audio/x-m4a": ".m4a",
+  "audio/mp4": ".m4a",
   "video/mp4": ".mp4",
+  "video/quicktime": ".mov",
   "application/pdf": ".pdf",
   "application/json": ".json",
   "application/zip": ".zip",

src/memory/backend-config.test.ts

@@ -1,58 +0,0 @@
-import path from "node:path";
-
-import { describe, expect, it } from "vitest";
-
-import type { MoltbotConfig } from "../config/config.js";
-import { resolveAgentWorkspaceDir } from "../agents/agent-scope.js";
-import { resolveMemoryBackendConfig } from "./backend-config.js";
-
-describe("resolveMemoryBackendConfig", () => {
-  it("defaults to builtin backend when config missing", () => {
-    const cfg = { agents: { defaults: { workspace: "/tmp/memory-test" } } } as MoltbotConfig;
-    const resolved = resolveMemoryBackendConfig({ cfg, agentId: "main" });
-    expect(resolved.backend).toBe("builtin");
-    expect(resolved.citations).toBe("auto");
-    expect(resolved.qmd).toBeUndefined();
-  });
-
-  it("resolves qmd backend with default collections", () => {
-    const cfg = {
-      agents: { defaults: { workspace: "/tmp/memory-test" } },
-      memory: {
-        backend: "qmd",
-        qmd: {},
-      },
-    } as MoltbotConfig;
-    const resolved = resolveMemoryBackendConfig({ cfg, agentId: "main" });
-    expect(resolved.backend).toBe("qmd");
-    expect(resolved.qmd?.collections.length).toBeGreaterThanOrEqual(3);
-    expect(resolved.qmd?.command).toBe("qmd");
-    expect(resolved.qmd?.update.intervalMs).toBeGreaterThan(0);
-  });
-
-  it("resolves custom paths relative to workspace", () => {
-    const cfg = {
-      agents: {
-        defaults: { workspace: "/workspace/root" },
-        list: [{ id: "main", workspace: "/workspace/root" }],
-      },
-      memory: {
-        backend: "qmd",
-        qmd: {
-          paths: [
-            {
-              path: "notes",
-              name: "custom-notes",
-              pattern: "**/*.md",
-            },
-          ],
-        },
-      },
-    } as MoltbotConfig;
-    const resolved = resolveMemoryBackendConfig({ cfg, agentId: "main" });
-    const custom = resolved.qmd?.collections.find((c) => c.name.startsWith("custom-notes"));
-    expect(custom).toBeDefined();
-    const workspaceRoot = resolveAgentWorkspaceDir(cfg, "main");
-    expect(custom?.path).toBe(path.resolve(workspaceRoot, "notes"));
-  });
-});

src/memory/backend-config.ts

@@ -1,255 +0,0 @@
-import path from "node:path";
-
-import { parseDurationMs } from "../cli/parse-duration.js";
-import { resolveAgentWorkspaceDir } from "../agents/agent-scope.js";
-import type { MoltbotConfig } from "../config/config.js";
-import type {
-  MemoryBackend,
-  MemoryCitationsMode,
-  MemoryQmdConfig,
-  MemoryQmdIndexPath,
-} from "../config/types.memory.js";
-import type { SessionSendPolicyConfig } from "../config/types.base.js";
-import { resolveUserPath } from "../utils.js";
-
-export type ResolvedMemoryBackendConfig = {
-  backend: MemoryBackend;
-  citations: MemoryCitationsMode;
-  qmd?: ResolvedQmdConfig;
-};
-
-export type ResolvedQmdCollection = {
-  name: string;
-  path: string;
-  pattern: string;
-  kind: "memory" | "custom" | "sessions";
-};
-
-export type ResolvedQmdUpdateConfig = {
-  intervalMs: number;
-  debounceMs: number;
-  onBoot: boolean;
-  embedIntervalMs: number;
-};
-
-export type ResolvedQmdLimitsConfig = {
-  maxResults: number;
-  maxSnippetChars: number;
-  maxInjectedChars: number;
-  timeoutMs: number;
-};
-
-export type ResolvedQmdSessionConfig = {
-  enabled: boolean;
-  exportDir?: string;
-  retentionDays?: number;
-};
-
-export type ResolvedQmdConfig = {
-  command: string;
-  collections: ResolvedQmdCollection[];
-  sessions: ResolvedQmdSessionConfig;
-  update: ResolvedQmdUpdateConfig;
-  limits: ResolvedQmdLimitsConfig;
-  includeDefaultMemory: boolean;
-  scope?: SessionSendPolicyConfig;
-};
-
-const DEFAULT_BACKEND: MemoryBackend = "builtin";
-const DEFAULT_CITATIONS: MemoryCitationsMode = "auto";
-const DEFAULT_QMD_INTERVAL = "5m";
-const DEFAULT_QMD_DEBOUNCE_MS = 15_000;
-const DEFAULT_QMD_TIMEOUT_MS = 4_000;
-const DEFAULT_QMD_EMBED_INTERVAL = "60m";
-const DEFAULT_QMD_LIMITS: ResolvedQmdLimitsConfig = {
-  maxResults: 6,
-  maxSnippetChars: 700,
-  maxInjectedChars: 4_000,
-  timeoutMs: DEFAULT_QMD_TIMEOUT_MS,
-};
-const DEFAULT_QMD_SCOPE: SessionSendPolicyConfig = {
-  default: "deny",
-  rules: [
-    {
-      action: "allow",
-      match: { chatType: "direct" },
-    },
-  ],
-};
-
-function sanitizeName(input: string): string {
-  const lower = input.toLowerCase().replace(/[^a-z0-9-]+/g, "-");
-  const trimmed = lower.replace(/^-+|-+$/g, "");
-  return trimmed || "collection";
-}
-
-function ensureUniqueName(base: string, existing: Set<string>): string {
-  let name = sanitizeName(base);
-  if (!existing.has(name)) {
-    existing.add(name);
-    return name;
-  }
-  let suffix = 2;
-  while (existing.has(`${name}-${suffix}`)) {
-    suffix += 1;
-  }
-  const unique = `${name}-${suffix}`;
-  existing.add(unique);
-  return unique;
-}
-
-function resolvePath(raw: string, workspaceDir: string): string {
-  const trimmed = raw.trim();
-  if (!trimmed) throw new Error("path required");
-  if (trimmed.startsWith("~") || path.isAbsolute(trimmed)) {
-    return path.normalize(resolveUserPath(trimmed));
-  }
-  return path.normalize(path.resolve(workspaceDir, trimmed));
-}
-
-function resolveIntervalMs(raw: string | undefined): number {
-  const value = raw?.trim();
-  if (!value) return parseDurationMs(DEFAULT_QMD_INTERVAL, { defaultUnit: "m" });
-  try {
-    return parseDurationMs(value, { defaultUnit: "m" });
-  } catch {
-    return parseDurationMs(DEFAULT_QMD_INTERVAL, { defaultUnit: "m" });
-  }
-}
-
-function resolveEmbedIntervalMs(raw: string | undefined): number {
-  const value = raw?.trim();
-  if (!value) return parseDurationMs(DEFAULT_QMD_EMBED_INTERVAL, { defaultUnit: "m" });
-  try {
-    return parseDurationMs(value, { defaultUnit: "m" });
-  } catch {
-    return parseDurationMs(DEFAULT_QMD_EMBED_INTERVAL, { defaultUnit: "m" });
-  }
-}
-
-function resolveDebounceMs(raw: number | undefined): number {
-  if (typeof raw === "number" && Number.isFinite(raw) && raw >= 0) {
-    return Math.floor(raw);
-  }
-  return DEFAULT_QMD_DEBOUNCE_MS;
-}
-
-function resolveLimits(raw?: MemoryQmdConfig["limits"]): ResolvedQmdLimitsConfig {
-  const parsed: ResolvedQmdLimitsConfig = { ...DEFAULT_QMD_LIMITS };
-  if (raw?.maxResults && raw.maxResults > 0) parsed.maxResults = Math.floor(raw.maxResults);
-  if (raw?.maxSnippetChars && raw.maxSnippetChars > 0) {
-    parsed.maxSnippetChars = Math.floor(raw.maxSnippetChars);
-  }
-  if (raw?.maxInjectedChars && raw.maxInjectedChars > 0) {
-    parsed.maxInjectedChars = Math.floor(raw.maxInjectedChars);
-  }
-  if (raw?.timeoutMs && raw.timeoutMs > 0) {
-    parsed.timeoutMs = Math.floor(raw.timeoutMs);
-  }
-  return parsed;
-}
-
-function resolveSessionConfig(
-  cfg: MemoryQmdConfig["sessions"],
-  workspaceDir: string,
-): ResolvedQmdSessionConfig {
-  const enabled = Boolean(cfg?.enabled);
-  const exportDirRaw = cfg?.exportDir?.trim();
-  const exportDir = exportDirRaw ? resolvePath(exportDirRaw, workspaceDir) : undefined;
-  const retentionDays =
-    cfg?.retentionDays && cfg.retentionDays > 0 ? Math.floor(cfg.retentionDays) : undefined;
-  return {
-    enabled,
-    exportDir,
-    retentionDays,
-  };
-}
-
-function resolveCustomPaths(
-  rawPaths: MemoryQmdIndexPath[] | undefined,
-  workspaceDir: string,
-  existing: Set<string>,
-): ResolvedQmdCollection[] {
-  if (!rawPaths?.length) return [];
-  const collections: ResolvedQmdCollection[] = [];
-  rawPaths.forEach((entry, index) => {
-    const trimmedPath = entry?.path?.trim();
-    if (!trimmedPath) return;
-    let resolved: string;
-    try {
-      resolved = resolvePath(trimmedPath, workspaceDir);
-    } catch {
-      return;
-    }
-    const pattern = entry.pattern?.trim() || "**/*.md";
-    const baseName = entry.name?.trim() || `custom-${index + 1}`;
-    const name = ensureUniqueName(baseName, existing);
-    collections.push({
-      name,
-      path: resolved,
-      pattern,
-      kind: "custom",
-    });
-  });
-  return collections;
-}
-
-function resolveDefaultCollections(
-  include: boolean,
-  workspaceDir: string,
-  existing: Set<string>,
-): ResolvedQmdCollection[] {
-  if (!include) return [];
-  const entries: Array<{ path: string; pattern: string; base: string }> = [
-    { path: workspaceDir, pattern: "MEMORY.md", base: "memory-root" },
-    { path: workspaceDir, pattern: "memory.md", base: "memory-alt" },
-    { path: path.join(workspaceDir, "memory"), pattern: "**/*.md", base: "memory-dir" },
-  ];
-  return entries.map((entry) => ({
-    name: ensureUniqueName(entry.base, existing),
-    path: entry.path,
-    pattern: entry.pattern,
-    kind: "memory",
-  }));
-}
-
-export function resolveMemoryBackendConfig(params: {
-  cfg: MoltbotConfig;
-  agentId: string;
-}): ResolvedMemoryBackendConfig {
-  const backend = params.cfg.memory?.backend ?? DEFAULT_BACKEND;
-  const citations = params.cfg.memory?.citations ?? DEFAULT_CITATIONS;
-  if (backend !== "qmd") {
-    return { backend: "builtin", citations };
-  }
-
-  const workspaceDir = resolveAgentWorkspaceDir(params.cfg, params.agentId);
-  const qmdCfg = params.cfg.memory?.qmd;
-  const includeDefaultMemory = qmdCfg?.includeDefaultMemory !== false;
-  const nameSet = new Set<string>();
-  const collections = [
-    ...resolveDefaultCollections(includeDefaultMemory, workspaceDir, nameSet),
-    ...resolveCustomPaths(qmdCfg?.paths, workspaceDir, nameSet),
-  ];
-
-  const resolved: ResolvedQmdConfig = {
-    command: (qmdCfg?.command?.trim() || "qmd").split(/\s+/)[0] || "qmd",
-    collections,
-    includeDefaultMemory,
-    sessions: resolveSessionConfig(qmdCfg?.sessions, workspaceDir),
-    update: {
-      intervalMs: resolveIntervalMs(qmdCfg?.update?.interval),
-      debounceMs: resolveDebounceMs(qmdCfg?.update?.debounceMs),
-      onBoot: qmdCfg?.update?.onBoot !== false,
-      embedIntervalMs: resolveEmbedIntervalMs(qmdCfg?.update?.embedInterval),
-    },
-    limits: resolveLimits(qmdCfg?.limits),
-    scope: qmdCfg?.scope ?? DEFAULT_QMD_SCOPE,
-  };
-
-  return {
-    backend: "qmd",
-    citations,
-    qmd: resolved,
-  };
-}

src/memory/index.test.ts

@@ -412,4 +412,52 @@ describe("memory index", () => {
     manager = result.manager;
     await expect(result.manager.readFile({ relPath: "NOTES.md" })).rejects.toThrow("path required");
   });
+
+  it("allows reading from additional memory paths and blocks symlinks", async () => {
+    const extraDir = path.join(workspaceDir, "extra");
+    await fs.mkdir(extraDir, { recursive: true });
+    await fs.writeFile(path.join(extraDir, "extra.md"), "Extra content.");
+
+    const cfg = {
+      agents: {
+        defaults: {
+          workspace: workspaceDir,
+          memorySearch: {
+            provider: "openai",
+            model: "mock-embed",
+            store: { path: indexPath },
+            sync: { watch: false, onSessionStart: false, onSearch: true },
+            extraPaths: [extraDir],
+          },
+        },
+        list: [{ id: "main", default: true }],
+      },
+    };
+    const result = await getMemorySearchManager({ cfg, agentId: "main" });
+    expect(result.manager).not.toBeNull();
+    if (!result.manager) throw new Error("manager missing");
+    manager = result.manager;
+    await expect(result.manager.readFile({ relPath: "extra/extra.md" })).resolves.toEqual({
+      path: "extra/extra.md",
+      text: "Extra content.",
+    });
+
+    const linkPath = path.join(extraDir, "linked.md");
+    let symlinkOk = true;
+    try {
+      await fs.symlink(path.join(extraDir, "extra.md"), linkPath, "file");
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code === "EPERM" || code === "EACCES") {
+        symlinkOk = false;
+      } else {
+        throw err;
+      }
+    }
+    if (symlinkOk) {
+      await expect(result.manager.readFile({ relPath: "extra/linked.md" })).rejects.toThrow(
+        "path required",
+      );
+    }
+  });
 });

src/memory/index.ts

@@ -1,7 +1,2 @@
-export { MemoryIndexManager } from "./manager.js";
-export type {
-  MemoryEmbeddingProbeResult,
-  MemorySearchManager,
-  MemorySearchResult,
-} from "./types.js";
+export type { MemoryIndexManager, MemorySearchResult } from "./manager.js";
 export { getMemorySearchManager, type MemorySearchManagerResult } from "./search-manager.js";

src/memory/internal.test.ts

@@ -1,6 +1,117 @@
-import { describe, expect, it } from "vitest";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
 
-import { chunkMarkdown } from "./internal.js";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { chunkMarkdown, listMemoryFiles, normalizeExtraMemoryPaths } from "./internal.js";
+
+describe("normalizeExtraMemoryPaths", () => {
+  it("trims, resolves, and dedupes paths", () => {
+    const workspaceDir = path.join(os.tmpdir(), "memory-test-workspace");
+    const absPath = path.resolve(path.sep, "shared-notes");
+    const result = normalizeExtraMemoryPaths(workspaceDir, [
+      " notes ",
+      "./notes",
+      absPath,
+      absPath,
+      "",
+    ]);
+    expect(result).toEqual([path.resolve(workspaceDir, "notes"), absPath]);
+  });
+});
+
+describe("listMemoryFiles", () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "memory-test-"));
+  });
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("includes files from additional paths (directory)", async () => {
+    await fs.writeFile(path.join(tmpDir, "MEMORY.md"), "# Default memory");
+    const extraDir = path.join(tmpDir, "extra-notes");
+    await fs.mkdir(extraDir, { recursive: true });
+    await fs.writeFile(path.join(extraDir, "note1.md"), "# Note 1");
+    await fs.writeFile(path.join(extraDir, "note2.md"), "# Note 2");
+    await fs.writeFile(path.join(extraDir, "ignore.txt"), "Not a markdown file");
+
+    const files = await listMemoryFiles(tmpDir, [extraDir]);
+    expect(files).toHaveLength(3);
+    expect(files.some((file) => file.endsWith("MEMORY.md"))).toBe(true);
+    expect(files.some((file) => file.endsWith("note1.md"))).toBe(true);
+    expect(files.some((file) => file.endsWith("note2.md"))).toBe(true);
+    expect(files.some((file) => file.endsWith("ignore.txt"))).toBe(false);
+  });
+
+  it("includes files from additional paths (single file)", async () => {
+    await fs.writeFile(path.join(tmpDir, "MEMORY.md"), "# Default memory");
+    const singleFile = path.join(tmpDir, "standalone.md");
+    await fs.writeFile(singleFile, "# Standalone");
+
+    const files = await listMemoryFiles(tmpDir, [singleFile]);
+    expect(files).toHaveLength(2);
+    expect(files.some((file) => file.endsWith("standalone.md"))).toBe(true);
+  });
+
+  it("handles relative paths in additional paths", async () => {
+    await fs.writeFile(path.join(tmpDir, "MEMORY.md"), "# Default memory");
+    const extraDir = path.join(tmpDir, "subdir");
+    await fs.mkdir(extraDir, { recursive: true });
+    await fs.writeFile(path.join(extraDir, "nested.md"), "# Nested");
+
+    const files = await listMemoryFiles(tmpDir, ["subdir"]);
+    expect(files).toHaveLength(2);
+    expect(files.some((file) => file.endsWith("nested.md"))).toBe(true);
+  });
+
+  it("ignores non-existent additional paths", async () => {
+    await fs.writeFile(path.join(tmpDir, "MEMORY.md"), "# Default memory");
+
+    const files = await listMemoryFiles(tmpDir, ["/does/not/exist"]);
+    expect(files).toHaveLength(1);
+  });
+
+  it("ignores symlinked files and directories", async () => {
+    await fs.writeFile(path.join(tmpDir, "MEMORY.md"), "# Default memory");
+    const extraDir = path.join(tmpDir, "extra");
+    await fs.mkdir(extraDir, { recursive: true });
+    await fs.writeFile(path.join(extraDir, "note.md"), "# Note");
+
+    const targetFile = path.join(tmpDir, "target.md");
+    await fs.writeFile(targetFile, "# Target");
+    const linkFile = path.join(extraDir, "linked.md");
+
+    const targetDir = path.join(tmpDir, "target-dir");
+    await fs.mkdir(targetDir, { recursive: true });
+    await fs.writeFile(path.join(targetDir, "nested.md"), "# Nested");
+    const linkDir = path.join(tmpDir, "linked-dir");
+
+    let symlinksOk = true;
+    try {
+      await fs.symlink(targetFile, linkFile, "file");
+      await fs.symlink(targetDir, linkDir, "dir");
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code === "EPERM" || code === "EACCES") {
+        symlinksOk = false;
+      } else {
+        throw err;
+      }
+    }
+
+    const files = await listMemoryFiles(tmpDir, [extraDir, linkDir]);
+    expect(files.some((file) => file.endsWith("note.md"))).toBe(true);
+    if (symlinksOk) {
+      expect(files.some((file) => file.endsWith("linked.md"))).toBe(false);
+      expect(files.some((file) => file.endsWith("nested.md"))).toBe(false);
+    }
+  });
+});
 
 describe("chunkMarkdown", () => {
   it("splits overly long lines into max-sized chunks", () => {

src/memory/internal.ts

@@ -30,6 +30,17 @@ export function normalizeRelPath(value: string): string {
   return trimmed.replace(/\\/g, "/");
 }
 
+export function normalizeExtraMemoryPaths(workspaceDir: string, extraPaths?: string[]): string[] {
+  if (!extraPaths?.length) return [];
+  const resolved = extraPaths
+    .map((value) => value.trim())
+    .filter(Boolean)
+    .map((value) =>
+      path.isAbsolute(value) ? path.resolve(value) : path.resolve(workspaceDir, value),
+    );
+  return Array.from(new Set(resolved));
+}
+
 export function isMemoryPath(relPath: string): boolean {
   const normalized = normalizeRelPath(relPath);
   if (!normalized) return false;
@@ -37,19 +48,11 @@ export function isMemoryPath(relPath: string): boolean {
   return normalized.startsWith("memory/");
 }
 
-async function exists(filePath: string): Promise<boolean> {
-  try {
-    await fs.access(filePath);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 async function walkDir(dir: string, files: string[]) {
   const entries = await fs.readdir(dir, { withFileTypes: true });
   for (const entry of entries) {
     const full = path.join(dir, entry.name);
+    if (entry.isSymbolicLink()) continue;
     if (entry.isDirectory()) {
       await walkDir(full, files);
       continue;
@@ -60,15 +63,48 @@ async function walkDir(dir: string, files: string[]) {
   }
 }
 
-export async function listMemoryFiles(workspaceDir: string): Promise<string[]> {
+export async function listMemoryFiles(
+  workspaceDir: string,
+  extraPaths?: string[],
+): Promise<string[]> {
   const result: string[] = [];
   const memoryFile = path.join(workspaceDir, "MEMORY.md");
   const altMemoryFile = path.join(workspaceDir, "memory.md");
-  if (await exists(memoryFile)) result.push(memoryFile);
-  if (await exists(altMemoryFile)) result.push(altMemoryFile);
   const memoryDir = path.join(workspaceDir, "memory");
-  if (await exists(memoryDir)) {
-    await walkDir(memoryDir, result);
+
+  const addMarkdownFile = async (absPath: string) => {
+    try {
+      const stat = await fs.lstat(absPath);
+      if (stat.isSymbolicLink() || !stat.isFile()) return;
+      if (!absPath.endsWith(".md")) return;
+      result.push(absPath);
+    } catch {}
+  };
+
+  await addMarkdownFile(memoryFile);
+  await addMarkdownFile(altMemoryFile);
+  try {
+    const dirStat = await fs.lstat(memoryDir);
+    if (!dirStat.isSymbolicLink() && dirStat.isDirectory()) {
+      await walkDir(memoryDir, result);
+    }
+  } catch {}
+
+  const normalizedExtraPaths = normalizeExtraMemoryPaths(workspaceDir, extraPaths);
+  if (normalizedExtraPaths.length > 0) {
+    for (const inputPath of normalizedExtraPaths) {
+      try {
+        const stat = await fs.lstat(inputPath);
+        if (stat.isSymbolicLink()) continue;
+        if (stat.isDirectory()) {
+          await walkDir(inputPath, result);
+          continue;
+        }
+        if (stat.isFile() && inputPath.endsWith(".md")) {
+          result.push(inputPath);
+        }
+      } catch {}
+    }
   }
   if (result.length <= 1) return result;
   const seen = new Set<string>();

src/memory/manager-cache-key.ts

@@ -13,6 +13,7 @@ export function computeMemoryManagerCacheKey(params: {
     JSON.stringify({
       enabled: settings.enabled,
       sources: [...settings.sources].sort((a, b) => a.localeCompare(b)),
+      extraPaths: [...settings.extraPaths].sort((a, b) => a.localeCompare(b)),
       provider: settings.provider,
       model: settings.model,
       fallback: settings.fallback,

src/memory/manager.ts

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 
@@ -35,9 +36,9 @@ import {
   hashText,
   isMemoryPath,
   listMemoryFiles,
+  normalizeExtraMemoryPaths,
   type MemoryChunk,
   type MemoryFileEntry,
-  normalizeRelPath,
   parseEmbedding,
 } from "./internal.js";
 import { bm25RankToScore, buildFtsQuery, mergeHybridResults } from "./hybrid.js";
@@ -45,14 +46,17 @@ import { searchKeyword, searchVector } from "./manager-search.js";
 import { ensureMemoryIndexSchema } from "./memory-schema.js";
 import { requireNodeSqlite } from "./sqlite.js";
 import { loadSqliteVecExtension } from "./sqlite-vec.js";
-import type {
-  MemoryEmbeddingProbeResult,
-  MemoryProviderStatus,
-  MemorySearchManager,
-  MemorySearchResult,
-  MemorySource,
-  MemorySyncProgressUpdate,
-} from "./types.js";
+
+type MemorySource = "memory" | "sessions";
+
+export type MemorySearchResult = {
+  path: string;
+  startLine: number;
+  endLine: number;
+  score: number;
+  snippet: string;
+  source: MemorySource;
+};
 
 type MemoryIndexMeta = {
   model: string;
@@ -72,6 +76,12 @@ type SessionFileEntry = {
   content: string;
 };
 
+type MemorySyncProgressUpdate = {
+  completed: number;
+  total: number;
+  label?: string;
+};
+
 type MemorySyncProgressState = {
   completed: number;
   total: number;
@@ -106,7 +116,7 @@ const INDEX_CACHE = new Map<string, MemoryIndexManager>();
 const vectorToBlob = (embedding: number[]): Buffer =>
   Buffer.from(new Float32Array(embedding).buffer);
 
-export class MemoryIndexManager implements MemorySearchManager {
+export class MemoryIndexManager {
   private readonly cacheKey: string;
   private readonly cfg: MoltbotConfig;
   private readonly agentId: string;
@@ -387,13 +397,52 @@ export class MemoryIndexManager implements MemorySearchManager {
     from?: number;
     lines?: number;
   }): Promise<{ text: string; path: string }> {
-    const relPath = normalizeRelPath(params.relPath);
-    if (!relPath || !isMemoryPath(relPath)) {
+    const rawPath = params.relPath.trim();
+    if (!rawPath) {
       throw new Error("path required");
     }
-    const absPath = path.resolve(this.workspaceDir, relPath);
-    if (!absPath.startsWith(this.workspaceDir)) {
-      throw new Error("path escapes workspace");
+    const absPath = path.isAbsolute(rawPath)
+      ? path.resolve(rawPath)
+      : path.resolve(this.workspaceDir, rawPath);
+    const relPath = path.relative(this.workspaceDir, absPath).replace(/\\/g, "/");
+    const inWorkspace =
+      relPath.length > 0 && !relPath.startsWith("..") && !path.isAbsolute(relPath);
+    const allowedWorkspace = inWorkspace && isMemoryPath(relPath);
+    let allowedAdditional = false;
+    if (!allowedWorkspace && this.settings.extraPaths.length > 0) {
+      const additionalPaths = normalizeExtraMemoryPaths(
+        this.workspaceDir,
+        this.settings.extraPaths,
+      );
+      for (const additionalPath of additionalPaths) {
+        try {
+          const stat = await fs.lstat(additionalPath);
+          if (stat.isSymbolicLink()) continue;
+          if (stat.isDirectory()) {
+            if (absPath === additionalPath || absPath.startsWith(`${additionalPath}${path.sep}`)) {
+              allowedAdditional = true;
+              break;
+            }
+            continue;
+          }
+          if (stat.isFile()) {
+            if (absPath === additionalPath && absPath.endsWith(".md")) {
+              allowedAdditional = true;
+              break;
+            }
+          }
+        } catch {}
+      }
+    }
+    if (!allowedWorkspace && !allowedAdditional) {
+      throw new Error("path required");
+    }
+    if (!absPath.endsWith(".md")) {
+      throw new Error("path required");
+    }
+    const stat = await fs.lstat(absPath);
+    if (stat.isSymbolicLink() || !stat.isFile()) {
+      throw new Error("path required");
     }
     const content = await fs.readFile(absPath, "utf-8");
     if (!params.from && !params.lines) {
@@ -406,7 +455,40 @@ export class MemoryIndexManager implements MemorySearchManager {
     return { text: slice.join("\n"), path: relPath };
   }
 
-  status(): MemoryProviderStatus {
+  status(): {
+    files: number;
+    chunks: number;
+    dirty: boolean;
+    workspaceDir: string;
+    dbPath: string;
+    provider: string;
+    model: string;
+    requestedProvider: string;
+    sources: MemorySource[];
+    extraPaths: string[];
+    sourceCounts: Array<{ source: MemorySource; files: number; chunks: number }>;
+    cache?: { enabled: boolean; entries?: number; maxEntries?: number };
+    fts?: { enabled: boolean; available: boolean; error?: string };
+    fallback?: { from: string; reason?: string };
+    vector?: {
+      enabled: boolean;
+      available?: boolean;
+      extensionPath?: string;
+      loadError?: string;
+      dims?: number;
+    };
+    batch?: {
+      enabled: boolean;
+      failures: number;
+      limit: number;
+      wait: boolean;
+      concurrency: number;
+      pollIntervalMs: number;
+      timeoutMs: number;
+      lastError?: string;
+      lastProvider?: string;
+    };
+  } {
     const sourceFilter = this.buildSourceFilter();
     const files = this.db
       .prepare(`SELECT COUNT(*) as c FROM files WHERE 1=1${sourceFilter.sql}`)
@@ -448,16 +530,16 @@ export class MemoryIndexManager implements MemorySearchManager {
       return sources.map((source) => ({ source, ...bySource.get(source)! }));
     })();
     return {
-      backend: "builtin",
       files: files?.c ?? 0,
       chunks: chunks?.c ?? 0,
-      dirty: this.dirty || this.sessionsDirty,
+      dirty: this.dirty,
       workspaceDir: this.workspaceDir,
       dbPath: this.settings.store.path,
       provider: this.provider.id,
       model: this.provider.model,
       requestedProvider: this.requestedProvider,
       sources: Array.from(this.sources),
+      extraPaths: this.settings.extraPaths,
       sourceCounts,
       cache: this.cache.enabled
         ? {
@@ -505,7 +587,7 @@ export class MemoryIndexManager implements MemorySearchManager {
     return this.ensureVectorReady();
   }
 
-  async probeEmbeddingAvailability(): Promise<MemoryEmbeddingProbeResult> {
+  async probeEmbeddingAvailability(): Promise<{ ok: boolean; error?: string }> {
     try {
       await this.embedBatchWithRetry(["ping"]);
       return { ok: true };
@@ -729,11 +811,23 @@ export class MemoryIndexManager implements MemorySearchManager {
 
   private ensureWatcher() {
     if (!this.sources.has("memory") || !this.settings.sync.watch || this.watcher) return;
-    const watchPaths = [
+    const additionalPaths = normalizeExtraMemoryPaths(this.workspaceDir, this.settings.extraPaths)
+      .map((entry) => {
+        try {
+          const stat = fsSync.lstatSync(entry);
+          return stat.isSymbolicLink() ? null : entry;
+        } catch {
+          return null;
+        }
+      })
+      .filter((entry): entry is string => Boolean(entry));
+    const watchPaths = new Set<string>([
       path.join(this.workspaceDir, "MEMORY.md"),
+      path.join(this.workspaceDir, "memory.md"),
       path.join(this.workspaceDir, "memory"),
-    ];
-    this.watcher = chokidar.watch(watchPaths, {
+      ...additionalPaths,
+    ]);
+    this.watcher = chokidar.watch(Array.from(watchPaths), {
       ignoreInitial: true,
       awaitWriteFinish: {
         stabilityThreshold: this.settings.sync.watchDebounceMs,
@@ -935,7 +1029,7 @@ export class MemoryIndexManager implements MemorySearchManager {
     needsFullReindex: boolean;
     progress?: MemorySyncProgressState;
   }) {
-    const files = await listMemoryFiles(this.workspaceDir);
+    const files = await listMemoryFiles(this.workspaceDir, this.settings.extraPaths);
     const fileEntries = await Promise.all(
       files.map(async (file) => buildFileEntry(file, this.workspaceDir)),
     );

src/memory/qmd-manager.test.ts

@@ -1,98 +0,0 @@
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { EventEmitter } from "node:events";
-
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-
-vi.mock("node:child_process", () => {
-  const spawn = vi.fn((_cmd: string, _args: string[]) => {
-    const stdout = new EventEmitter();
-    const stderr = new EventEmitter();
-    const child = new EventEmitter() as {
-      stdout: EventEmitter;
-      stderr: EventEmitter;
-      kill: () => void;
-      emit: (event: string, code: number) => boolean;
-    };
-    child.stdout = stdout;
-    child.stderr = stderr;
-    child.kill = () => {
-      child.emit("close", 0);
-    };
-    setImmediate(() => {
-      stdout.emit("data", "");
-      stderr.emit("data", "");
-      child.emit("close", 0);
-    });
-    return child;
-  });
-  return { spawn };
-});
-
-import { spawn as mockedSpawn } from "node:child_process";
-import type { MoltbotConfig } from "../config/config.js";
-import { resolveMemoryBackendConfig } from "./backend-config.js";
-import { QmdMemoryManager } from "./qmd-manager.js";
-
-const spawnMock = mockedSpawn as unknown as vi.Mock;
-
-describe("QmdMemoryManager", () => {
-  let tmpRoot: string;
-  let workspaceDir: string;
-  let stateDir: string;
-  let cfg: MoltbotConfig;
-  const agentId = "main";
-
-  beforeEach(async () => {
-    spawnMock.mockClear();
-    tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), "qmd-manager-test-"));
-    workspaceDir = path.join(tmpRoot, "workspace");
-    await fs.mkdir(workspaceDir, { recursive: true });
-    stateDir = path.join(tmpRoot, "state");
-    await fs.mkdir(stateDir, { recursive: true });
-    process.env.MOLTBOT_STATE_DIR = stateDir;
-    cfg = {
-      agents: {
-        list: [{ id: agentId, default: true, workspace: workspaceDir }],
-      },
-      memory: {
-        backend: "qmd",
-        qmd: {
-          includeDefaultMemory: false,
-          update: { interval: "0s", debounceMs: 60_000, onBoot: false },
-          paths: [{ path: workspaceDir, pattern: "**/*.md", name: "workspace" }],
-        },
-      },
-    } as MoltbotConfig;
-  });
-
-  afterEach(async () => {
-    delete process.env.MOLTBOT_STATE_DIR;
-    await fs.rm(tmpRoot, { recursive: true, force: true });
-  });
-
-  it("debounces back-to-back sync calls", async () => {
-    const resolved = resolveMemoryBackendConfig({ cfg, agentId });
-    const manager = await QmdMemoryManager.create({ cfg, agentId, resolved });
-    expect(manager).toBeTruthy();
-    if (!manager) throw new Error("manager missing");
-
-    const baselineCalls = spawnMock.mock.calls.length;
-
-    await manager.sync({ reason: "manual" });
-    expect(spawnMock.mock.calls.length).toBe(baselineCalls + 2);
-
-    await manager.sync({ reason: "manual-again" });
-    expect(spawnMock.mock.calls.length).toBe(baselineCalls + 2);
-
-    (manager as unknown as { lastUpdateAt: number | null }).lastUpdateAt =
-      Date.now() - (resolved.qmd?.update.debounceMs ?? 0) - 10;
-
-    await manager.sync({ reason: "after-wait" });
-    // By default we refresh embeddings less frequently than index updates.
-    expect(spawnMock.mock.calls.length).toBe(baselineCalls + 3);
-
-    await manager.close();
-  });
-});

src/memory/qmd-manager.ts

@@ -1,684 +0,0 @@
-import { spawn } from "node:child_process";
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-
-import type { MoltbotConfig } from "../config/config.js";
-import { resolveStateDir } from "../config/paths.js";
-import { resolveAgentWorkspaceDir } from "../agents/agent-scope.js";
-import { createSubsystemLogger } from "../logging/subsystem.js";
-import {
-  listSessionFilesForAgent,
-  buildSessionEntry,
-  type SessionFileEntry,
-} from "./session-files.js";
-import { requireNodeSqlite } from "./sqlite.js";
-import type {
-  MemoryEmbeddingProbeResult,
-  MemoryProviderStatus,
-  MemorySearchManager,
-  MemorySearchResult,
-  MemorySource,
-  MemorySyncProgressUpdate,
-} from "./types.js";
-
-type SqliteDatabase = import("node:sqlite").DatabaseSync;
-import type { ResolvedMemoryBackendConfig, ResolvedQmdConfig } from "./backend-config.js";
-
-const log = createSubsystemLogger("memory");
-
-const SNIPPET_HEADER_RE = /@@\s*-([0-9]+),([0-9]+)/;
-
-type QmdQueryResult = {
-  docid?: string;
-  score?: number;
-  file?: string;
-  snippet?: string;
-  body?: string;
-};
-
-type CollectionRoot = {
-  path: string;
-  kind: MemorySource;
-};
-
-type SessionExporterConfig = {
-  dir: string;
-  retentionMs?: number;
-  collectionName: string;
-};
-
-export class QmdMemoryManager implements MemorySearchManager {
-  static async create(params: {
-    cfg: MoltbotConfig;
-    agentId: string;
-    resolved: ResolvedMemoryBackendConfig;
-  }): Promise<QmdMemoryManager | null> {
-    const resolved = params.resolved.qmd;
-    if (!resolved) return null;
-    const manager = new QmdMemoryManager({ cfg: params.cfg, agentId: params.agentId, resolved });
-    await manager.initialize();
-    return manager;
-  }
-
-  private readonly cfg: MoltbotConfig;
-  private readonly agentId: string;
-  private readonly qmd: ResolvedQmdConfig;
-  private readonly workspaceDir: string;
-  private readonly stateDir: string;
-  private readonly agentStateDir: string;
-  private readonly qmdDir: string;
-  private readonly xdgConfigHome: string;
-  private readonly xdgCacheHome: string;
-  private readonly indexPath: string;
-  private readonly env: NodeJS.ProcessEnv;
-  private readonly collectionRoots = new Map<string, CollectionRoot>();
-  private readonly sources = new Set<MemorySource>();
-  private readonly docPathCache = new Map<
-    string,
-    { rel: string; abs: string; source: MemorySource }
-  >();
-  private readonly sessionExporter: SessionExporterConfig | null;
-  private updateTimer: NodeJS.Timeout | null = null;
-  private pendingUpdate: Promise<void> | null = null;
-  private closed = false;
-  private db: SqliteDatabase | null = null;
-  private lastUpdateAt: number | null = null;
-  private lastEmbedAt: number | null = null;
-
-  private constructor(params: {
-    cfg: MoltbotConfig;
-    agentId: string;
-    resolved: ResolvedQmdConfig;
-  }) {
-    this.cfg = params.cfg;
-    this.agentId = params.agentId;
-    this.qmd = params.resolved;
-    this.workspaceDir = resolveAgentWorkspaceDir(params.cfg, params.agentId);
-    this.stateDir = resolveStateDir(process.env, os.homedir);
-    this.agentStateDir = path.join(this.stateDir, "agents", this.agentId);
-    this.qmdDir = path.join(this.agentStateDir, "qmd");
-    // QMD uses XDG base dirs for its internal state.
-    // Collections are managed via `qmd collection add` and stored inside the index DB.
-    // - config:  $XDG_CONFIG_HOME (contexts, etc.)
-    // - cache:   $XDG_CACHE_HOME/qmd/index.sqlite
-    this.xdgConfigHome = path.join(this.qmdDir, "xdg-config");
-    this.xdgCacheHome = path.join(this.qmdDir, "xdg-cache");
-    this.indexPath = path.join(this.xdgCacheHome, "qmd", "index.sqlite");
-
-    this.env = {
-      ...process.env,
-      XDG_CONFIG_HOME: this.xdgConfigHome,
-      XDG_CACHE_HOME: this.xdgCacheHome,
-      NO_COLOR: "1",
-    };
-    this.sessionExporter = this.qmd.sessions.enabled
-      ? {
-          dir: this.qmd.sessions.exportDir ?? path.join(this.qmdDir, "sessions"),
-          retentionMs: this.qmd.sessions.retentionDays
-            ? this.qmd.sessions.retentionDays * 24 * 60 * 60 * 1000
-            : undefined,
-          collectionName: this.pickSessionCollectionName(),
-        }
-      : null;
-    if (this.sessionExporter) {
-      this.qmd.collections = [
-        ...this.qmd.collections,
-        {
-          name: this.sessionExporter.collectionName,
-          path: this.sessionExporter.dir,
-          pattern: "**/*.md",
-          kind: "sessions",
-        },
-      ];
-    }
-  }
-
-  private async initialize(): Promise<void> {
-    await fs.mkdir(this.xdgConfigHome, { recursive: true });
-    await fs.mkdir(this.xdgCacheHome, { recursive: true });
-    await fs.mkdir(path.dirname(this.indexPath), { recursive: true });
-
-    this.bootstrapCollections();
-    await this.ensureCollections();
-
-    if (this.qmd.update.onBoot) {
-      await this.runUpdate("boot", true);
-    }
-    if (this.qmd.update.intervalMs > 0) {
-      this.updateTimer = setInterval(() => {
-        void this.runUpdate("interval").catch((err) => {
-          log.warn(`qmd update failed (${String(err)})`);
-        });
-      }, this.qmd.update.intervalMs);
-    }
-  }
-
-  private bootstrapCollections(): void {
-    this.collectionRoots.clear();
-    this.sources.clear();
-    for (const collection of this.qmd.collections) {
-      const kind: MemorySource = collection.kind === "sessions" ? "sessions" : "memory";
-      this.collectionRoots.set(collection.name, { path: collection.path, kind });
-      this.sources.add(kind);
-    }
-  }
-
-  private async ensureCollections(): Promise<void> {
-    // QMD collections are persisted inside the index database and must be created
-    // via the CLI. Prefer listing existing collections when supported, otherwise
-    // fall back to best-effort idempotent `qmd collection add`.
-    const existing = new Set<string>();
-    try {
-      const result = await this.runQmd(["collection", "list", "--json"]);
-      const parsed = JSON.parse(result.stdout) as unknown;
-      if (Array.isArray(parsed)) {
-        for (const entry of parsed) {
-          if (typeof entry === "string") existing.add(entry);
-          else if (entry && typeof entry === "object") {
-            const name = (entry as { name?: unknown }).name;
-            if (typeof name === "string") existing.add(name);
-          }
-        }
-      }
-    } catch {
-      // ignore; older qmd versions might not support list --json.
-    }
-
-    for (const collection of this.qmd.collections) {
-      if (existing.has(collection.name)) continue;
-      try {
-        await this.runQmd([
-          "collection",
-          "add",
-          collection.path,
-          "--name",
-          collection.name,
-          "--mask",
-          collection.pattern,
-        ]);
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        // Idempotency: qmd exits non-zero if the collection name already exists.
-        if (message.toLowerCase().includes("already exists")) continue;
-        if (message.toLowerCase().includes("exists")) continue;
-        log.warn(`qmd collection add failed for ${collection.name}: ${message}`);
-      }
-    }
-  }
-
-  async search(
-    query: string,
-    opts?: { maxResults?: number; minScore?: number; sessionKey?: string },
-  ): Promise<MemorySearchResult[]> {
-    if (!this.isScopeAllowed(opts?.sessionKey)) return [];
-    const trimmed = query.trim();
-    if (!trimmed) return [];
-    await this.pendingUpdate?.catch(() => undefined);
-    const limit = Math.min(
-      this.qmd.limits.maxResults,
-      opts?.maxResults ?? this.qmd.limits.maxResults,
-    );
-    const args = ["query", trimmed, "--json", "-n", String(limit)];
-    let stdout: string;
-    try {
-      const result = await this.runQmd(args, { timeoutMs: this.qmd.limits.timeoutMs });
-      stdout = result.stdout;
-    } catch (err) {
-      log.warn(`qmd query failed: ${String(err)}`);
-      throw err instanceof Error ? err : new Error(String(err));
-    }
-    let parsed: QmdQueryResult[] = [];
-    try {
-      parsed = JSON.parse(stdout);
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      log.warn(`qmd query returned invalid JSON: ${message}`);
-      throw new Error(`qmd query returned invalid JSON: ${message}`);
-    }
-    const results: MemorySearchResult[] = [];
-    for (const entry of parsed) {
-      const doc = await this.resolveDocLocation(entry.docid);
-      if (!doc) continue;
-      const snippet = entry.snippet?.slice(0, this.qmd.limits.maxSnippetChars) ?? "";
-      const lines = this.extractSnippetLines(snippet);
-      const score = typeof entry.score === "number" ? entry.score : 0;
-      const minScore = opts?.minScore ?? 0;
-      if (score < minScore) continue;
-      results.push({
-        path: doc.rel,
-        startLine: lines.startLine,
-        endLine: lines.endLine,
-        score,
-        snippet,
-        source: doc.source,
-      });
-    }
-    return this.clampResultsByInjectedChars(results.slice(0, limit));
-  }
-
-  async sync(params?: {
-    reason?: string;
-    force?: boolean;
-    progress?: (update: MemorySyncProgressUpdate) => void;
-  }): Promise<void> {
-    if (params?.progress) {
-      params.progress({ completed: 0, total: 1, label: "Updating QMD index…" });
-    }
-    await this.runUpdate(params?.reason ?? "manual", params?.force);
-    if (params?.progress) {
-      params.progress({ completed: 1, total: 1, label: "QMD index updated" });
-    }
-  }
-
-  async readFile(params: {
-    relPath: string;
-    from?: number;
-    lines?: number;
-  }): Promise<{ text: string; path: string }> {
-    const relPath = params.relPath?.trim();
-    if (!relPath) throw new Error("path required");
-    const absPath = this.resolveReadPath(relPath);
-    const content = await fs.readFile(absPath, "utf-8");
-    if (!params.from && !params.lines) {
-      return { text: content, path: relPath };
-    }
-    const lines = content.split("\n");
-    const start = Math.max(1, params.from ?? 1);
-    const count = Math.max(1, params.lines ?? lines.length);
-    const slice = lines.slice(start - 1, start - 1 + count);
-    return { text: slice.join("\n"), path: relPath };
-  }
-
-  status(): MemoryProviderStatus {
-    const counts = this.readCounts();
-    return {
-      backend: "qmd",
-      provider: "qmd",
-      model: "qmd",
-      requestedProvider: "qmd",
-      files: counts.totalDocuments,
-      chunks: counts.totalDocuments,
-      dirty: false,
-      workspaceDir: this.workspaceDir,
-      dbPath: this.indexPath,
-      sources: Array.from(this.sources),
-      sourceCounts: counts.sourceCounts,
-      vector: { enabled: true, available: true },
-      batch: {
-        enabled: false,
-        failures: 0,
-        limit: 0,
-        wait: false,
-        concurrency: 0,
-        pollIntervalMs: 0,
-        timeoutMs: 0,
-      },
-      custom: {
-        qmd: {
-          collections: this.qmd.collections.length,
-          lastUpdateAt: this.lastUpdateAt,
-        },
-      },
-    };
-  }
-
-  async probeEmbeddingAvailability(): Promise<MemoryEmbeddingProbeResult> {
-    return { ok: true };
-  }
-
-  async probeVectorAvailability(): Promise<boolean> {
-    return true;
-  }
-
-  async close(): Promise<void> {
-    if (this.closed) return;
-    this.closed = true;
-    if (this.updateTimer) {
-      clearInterval(this.updateTimer);
-      this.updateTimer = null;
-    }
-    await this.pendingUpdate?.catch(() => undefined);
-    if (this.db) {
-      this.db.close();
-      this.db = null;
-    }
-  }
-
-  private async runUpdate(reason: string, force?: boolean): Promise<void> {
-    if (this.pendingUpdate && !force) return this.pendingUpdate;
-    if (this.shouldSkipUpdate(force)) {
-      return;
-    }
-    const run = async () => {
-      if (this.sessionExporter) {
-        await this.exportSessions();
-      }
-      await this.runQmd(["update"], { timeoutMs: 120_000 });
-      const embedIntervalMs = this.qmd.update.embedIntervalMs;
-      const shouldEmbed =
-        Boolean(force) ||
-        this.lastEmbedAt === null ||
-        (embedIntervalMs > 0 && Date.now() - this.lastEmbedAt > embedIntervalMs);
-      if (shouldEmbed) {
-        try {
-          await this.runQmd(["embed"], { timeoutMs: 120_000 });
-          this.lastEmbedAt = Date.now();
-        } catch (err) {
-          log.warn(`qmd embed failed (${reason}): ${String(err)}`);
-        }
-      }
-      this.lastUpdateAt = Date.now();
-      this.docPathCache.clear();
-    };
-    this.pendingUpdate = run().finally(() => {
-      this.pendingUpdate = null;
-    });
-    await this.pendingUpdate;
-  }
-
-  private async runQmd(
-    args: string[],
-    opts?: { timeoutMs?: number },
-  ): Promise<{ stdout: string; stderr: string }> {
-    return await new Promise((resolve, reject) => {
-      const child = spawn(this.qmd.command, args, {
-        env: this.env,
-        cwd: this.workspaceDir,
-      });
-      let stdout = "";
-      let stderr = "";
-      const timer = opts?.timeoutMs
-        ? setTimeout(() => {
-            child.kill("SIGKILL");
-            reject(new Error(`qmd ${args.join(" ")} timed out after ${opts.timeoutMs}ms`));
-          }, opts.timeoutMs)
-        : null;
-      child.stdout.on("data", (data) => {
-        stdout += data.toString();
-      });
-      child.stderr.on("data", (data) => {
-        stderr += data.toString();
-      });
-      child.on("error", (err) => {
-        if (timer) clearTimeout(timer);
-        reject(err);
-      });
-      child.on("close", (code) => {
-        if (timer) clearTimeout(timer);
-        if (code === 0) {
-          resolve({ stdout, stderr });
-        } else {
-          reject(new Error(`qmd ${args.join(" ")} failed (code ${code}): ${stderr || stdout}`));
-        }
-      });
-    });
-  }
-
-  private ensureDb(): SqliteDatabase {
-    if (this.db) return this.db;
-    const { DatabaseSync } = requireNodeSqlite();
-    this.db = new DatabaseSync(this.indexPath, { readOnly: true });
-    return this.db;
-  }
-
-  private async exportSessions(): Promise<void> {
-    if (!this.sessionExporter) return;
-    const exportDir = this.sessionExporter.dir;
-    await fs.mkdir(exportDir, { recursive: true });
-    const files = await listSessionFilesForAgent(this.agentId);
-    const keep = new Set<string>();
-    const cutoff = this.sessionExporter.retentionMs
-      ? Date.now() - this.sessionExporter.retentionMs
-      : null;
-    for (const sessionFile of files) {
-      const entry = await buildSessionEntry(sessionFile);
-      if (!entry) continue;
-      if (cutoff && entry.mtimeMs < cutoff) continue;
-      const target = path.join(exportDir, `${path.basename(sessionFile, ".jsonl")}.md`);
-      await fs.writeFile(target, this.renderSessionMarkdown(entry), "utf-8");
-      keep.add(target);
-    }
-    const exported = await fs.readdir(exportDir).catch(() => []);
-    for (const name of exported) {
-      if (!name.endsWith(".md")) continue;
-      const full = path.join(exportDir, name);
-      if (!keep.has(full)) {
-        await fs.rm(full, { force: true });
-      }
-    }
-  }
-
-  private renderSessionMarkdown(entry: SessionFileEntry): string {
-    const header = `# Session ${path.basename(entry.absPath, path.extname(entry.absPath))}`;
-    const body = entry.content?.trim().length ? entry.content.trim() : "(empty)";
-    return `${header}\n\n${body}\n`;
-  }
-
-  private pickSessionCollectionName(): string {
-    const existing = new Set(this.qmd.collections.map((collection) => collection.name));
-    if (!existing.has("sessions")) return "sessions";
-    let counter = 2;
-    let candidate = `sessions-${counter}`;
-    while (existing.has(candidate)) {
-      counter += 1;
-      candidate = `sessions-${counter}`;
-    }
-    return candidate;
-  }
-
-  private async resolveDocLocation(
-    docid?: string,
-  ): Promise<{ rel: string; abs: string; source: MemorySource } | null> {
-    if (!docid) return null;
-    const normalized = docid.startsWith("#") ? docid.slice(1) : docid;
-    if (!normalized) return null;
-    const cached = this.docPathCache.get(normalized);
-    if (cached) return cached;
-    const db = this.ensureDb();
-    const row = db
-      .prepare("SELECT collection, path FROM documents WHERE hash LIKE ? AND active = 1 LIMIT 1")
-      .get(`${normalized}%`) as { collection: string; path: string } | undefined;
-    if (!row) return null;
-    const location = this.toDocLocation(row.collection, row.path);
-    if (!location) return null;
-    this.docPathCache.set(normalized, location);
-    return location;
-  }
-
-  private extractSnippetLines(snippet: string): { startLine: number; endLine: number } {
-    const match = SNIPPET_HEADER_RE.exec(snippet);
-    if (match) {
-      const start = Number(match[1]);
-      const count = Number(match[2]);
-      if (Number.isFinite(start) && Number.isFinite(count)) {
-        return { startLine: start, endLine: start + count - 1 };
-      }
-    }
-    const lines = snippet.split("\n").length;
-    return { startLine: 1, endLine: lines };
-  }
-
-  private readCounts(): {
-    totalDocuments: number;
-    sourceCounts: Array<{ source: MemorySource; files: number; chunks: number }>;
-  } {
-    try {
-      const db = this.ensureDb();
-      const rows = db
-        .prepare(
-          "SELECT collection, COUNT(*) as c FROM documents WHERE active = 1 GROUP BY collection",
-        )
-        .all() as Array<{ collection: string; c: number }>;
-      const bySource = new Map<MemorySource, { files: number; chunks: number }>();
-      for (const source of this.sources) {
-        bySource.set(source, { files: 0, chunks: 0 });
-      }
-      let total = 0;
-      for (const row of rows) {
-        const root = this.collectionRoots.get(row.collection);
-        const source = root?.kind ?? "memory";
-        const entry = bySource.get(source) ?? { files: 0, chunks: 0 };
-        entry.files += row.c ?? 0;
-        entry.chunks += row.c ?? 0;
-        bySource.set(source, entry);
-        total += row.c ?? 0;
-      }
-      return {
-        totalDocuments: total,
-        sourceCounts: Array.from(bySource.entries()).map(([source, value]) => ({
-          source,
-          files: value.files,
-          chunks: value.chunks,
-        })),
-      };
-    } catch (err) {
-      log.warn(`failed to read qmd index stats: ${String(err)}`);
-      return {
-        totalDocuments: 0,
-        sourceCounts: Array.from(this.sources).map((source) => ({ source, files: 0, chunks: 0 })),
-      };
-    }
-  }
-
-  private isScopeAllowed(sessionKey?: string): boolean {
-    const scope = this.qmd.scope;
-    if (!scope) return true;
-    const channel = this.deriveChannelFromKey(sessionKey);
-    const chatType = this.deriveChatTypeFromKey(sessionKey);
-    const normalizedKey = sessionKey ?? "";
-    for (const rule of scope.rules ?? []) {
-      if (!rule) continue;
-      const match = rule.match ?? {};
-      if (match.channel && match.channel !== channel) continue;
-      if (match.chatType && match.chatType !== chatType) continue;
-      if (match.keyPrefix && !normalizedKey.startsWith(match.keyPrefix)) continue;
-      return rule.action === "allow";
-    }
-    const fallback = scope.default ?? "allow";
-    return fallback === "allow";
-  }
-
-  private deriveChannelFromKey(key?: string) {
-    if (!key) return undefined;
-    const parts = key.split(":").filter(Boolean);
-    if (parts.length >= 3 && (parts[1] === "group" || parts[1] === "channel")) {
-      return parts[0]?.toLowerCase();
-    }
-    return undefined;
-  }
-
-  private deriveChatTypeFromKey(key?: string) {
-    if (!key) return undefined;
-    if (key.includes(":group:")) return "group";
-    if (key.includes(":channel:")) return "channel";
-    return "direct";
-  }
-
-  private toDocLocation(
-    collection: string,
-    collectionRelativePath: string,
-  ): { rel: string; abs: string; source: MemorySource } | null {
-    const root = this.collectionRoots.get(collection);
-    if (!root) return null;
-    const normalizedRelative = collectionRelativePath.replace(/\\/g, "/");
-    const absPath = path.normalize(path.resolve(root.path, collectionRelativePath));
-    const relativeToWorkspace = path.relative(this.workspaceDir, absPath);
-    const relPath = this.buildSearchPath(
-      collection,
-      normalizedRelative,
-      relativeToWorkspace,
-      absPath,
-    );
-    return { rel: relPath, abs: absPath, source: root.kind };
-  }
-
-  private buildSearchPath(
-    collection: string,
-    collectionRelativePath: string,
-    relativeToWorkspace: string,
-    absPath: string,
-  ): string {
-    const insideWorkspace = this.isInsideWorkspace(relativeToWorkspace);
-    if (insideWorkspace) {
-      const normalized = relativeToWorkspace.replace(/\\/g, "/");
-      if (!normalized) return path.basename(absPath);
-      return normalized;
-    }
-    const sanitized = collectionRelativePath.replace(/^\/+/, "");
-    return `qmd/${collection}/${sanitized}`;
-  }
-
-  private isInsideWorkspace(relativePath: string): boolean {
-    if (!relativePath) return true;
-    if (relativePath.startsWith("..")) return false;
-    if (relativePath.startsWith(`..${path.sep}`)) return false;
-    return !path.isAbsolute(relativePath);
-  }
-
-  private resolveReadPath(relPath: string): string {
-    if (relPath.startsWith("qmd/")) {
-      const [, collection, ...rest] = relPath.split("/");
-      if (!collection || rest.length === 0) {
-        throw new Error("invalid qmd path");
-      }
-      const root = this.collectionRoots.get(collection);
-      if (!root) throw new Error(`unknown qmd collection: ${collection}`);
-      const joined = rest.join("/");
-      const resolved = path.resolve(root.path, joined);
-      if (!this.isWithinRoot(root.path, resolved)) {
-        throw new Error("qmd path escapes collection");
-      }
-      return resolved;
-    }
-    const absPath = path.resolve(this.workspaceDir, relPath);
-    if (!this.isWithinWorkspace(absPath)) {
-      throw new Error("path escapes workspace");
-    }
-    return absPath;
-  }
-
-  private isWithinWorkspace(absPath: string): boolean {
-    const normalizedWorkspace = this.workspaceDir.endsWith(path.sep)
-      ? this.workspaceDir
-      : `${this.workspaceDir}${path.sep}`;
-    if (absPath === this.workspaceDir) return true;
-    const candidate = absPath.endsWith(path.sep) ? absPath : `${absPath}${path.sep}`;
-    return candidate.startsWith(normalizedWorkspace);
-  }
-
-  private isWithinRoot(root: string, candidate: string): boolean {
-    const normalizedRoot = root.endsWith(path.sep) ? root : `${root}${path.sep}`;
-    if (candidate === root) return true;
-    const next = candidate.endsWith(path.sep) ? candidate : `${candidate}${path.sep}`;
-    return next.startsWith(normalizedRoot);
-  }
-
-  private clampResultsByInjectedChars(results: MemorySearchResult[]): MemorySearchResult[] {
-    const budget = this.qmd.limits.maxInjectedChars;
-    if (!budget || budget <= 0) return results;
-    let remaining = budget;
-    const clamped: MemorySearchResult[] = [];
-    for (const entry of results) {
-      if (remaining <= 0) break;
-      const snippet = entry.snippet ?? "";
-      if (snippet.length <= remaining) {
-        clamped.push(entry);
-        remaining -= snippet.length;
-      } else {
-        const trimmed = snippet.slice(0, Math.max(0, remaining));
-        clamped.push({ ...entry, snippet: trimmed });
-        break;
-      }
-    }
-    return clamped;
-  }
-
-  private shouldSkipUpdate(force?: boolean): boolean {
-    if (force) return false;
-    const debounceMs = this.qmd.update.debounceMs;
-    if (debounceMs <= 0) return false;
-    if (!this.lastUpdateAt) return false;
-    return Date.now() - this.lastUpdateAt < debounceMs;
-  }
-}

src/memory/search-manager.test.ts

@@ -1,65 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
-
-const mockPrimary = {
-  search: vi.fn(async () => []),
-  readFile: vi.fn(async () => ({ text: "", path: "MEMORY.md" })),
-  status: vi.fn(() => ({
-    backend: "qmd" as const,
-    provider: "qmd",
-    model: "qmd",
-    requestedProvider: "qmd",
-    files: 0,
-    chunks: 0,
-    dirty: false,
-    workspaceDir: "/tmp",
-    dbPath: "/tmp/index.sqlite",
-    sources: ["memory" as const],
-    sourceCounts: [{ source: "memory" as const, files: 0, chunks: 0 }],
-  })),
-  sync: vi.fn(async () => {}),
-  probeEmbeddingAvailability: vi.fn(async () => ({ ok: true })),
-  probeVectorAvailability: vi.fn(async () => true),
-  close: vi.fn(async () => {}),
-};
-
-vi.mock("./qmd-manager.js", () => ({
-  QmdMemoryManager: {
-    create: vi.fn(async () => mockPrimary),
-  },
-}));
-
-vi.mock("./manager.js", () => ({
-  MemoryIndexManager: {
-    get: vi.fn(async () => null),
-  },
-}));
-
-import { QmdMemoryManager } from "./qmd-manager.js";
-import { getMemorySearchManager } from "./search-manager.js";
-
-beforeEach(() => {
-  mockPrimary.search.mockClear();
-  mockPrimary.readFile.mockClear();
-  mockPrimary.status.mockClear();
-  mockPrimary.sync.mockClear();
-  mockPrimary.probeEmbeddingAvailability.mockClear();
-  mockPrimary.probeVectorAvailability.mockClear();
-  mockPrimary.close.mockClear();
-  QmdMemoryManager.create.mockClear();
-});
-
-describe("getMemorySearchManager caching", () => {
-  it("reuses the same QMD manager instance for repeated calls", async () => {
-    const cfg = {
-      memory: { backend: "qmd", qmd: {} },
-      agents: { list: [{ id: "main", default: true, workspace: "/tmp/workspace" }] },
-    } as const;
-
-    const first = await getMemorySearchManager({ cfg, agentId: "main" });
-    const second = await getMemorySearchManager({ cfg, agentId: "main" });
-
-    expect(first.manager).toBe(second.manager);
-    // eslint-disable-next-line @typescript-eslint/unbound-method
-    expect(QmdMemoryManager.create).toHaveBeenCalledTimes(1);
-  });
-});

src/memory/search-manager.ts

@@ -1,18 +1,8 @@
-import { createSubsystemLogger } from "../logging/subsystem.js";
 import type { MoltbotConfig } from "../config/config.js";
-import { resolveMemoryBackendConfig } from "./backend-config.js";
-import type { ResolvedQmdConfig } from "./backend-config.js";
-import type {
-  MemoryEmbeddingProbeResult,
-  MemorySearchManager,
-  MemorySyncProgressUpdate,
-} from "./types.js";
-
-const log = createSubsystemLogger("memory");
-const QMD_MANAGER_CACHE = new Map<string, MemorySearchManager>();
+import type { MemoryIndexManager } from "./manager.js";
 
 export type MemorySearchManagerResult = {
-  manager: MemorySearchManager | null;
+  manager: MemoryIndexManager | null;
   error?: string;
 };
 
@@ -20,40 +10,6 @@ export async function getMemorySearchManager(params: {
   cfg: MoltbotConfig;
   agentId: string;
 }): Promise<MemorySearchManagerResult> {
-  const resolved = resolveMemoryBackendConfig(params);
-  if (resolved.backend === "qmd" && resolved.qmd) {
-    const cacheKey = buildQmdCacheKey(params.agentId, resolved.qmd);
-    const cached = QMD_MANAGER_CACHE.get(cacheKey);
-    if (cached) {
-      return { manager: cached };
-    }
-    try {
-      const { QmdMemoryManager } = await import("./qmd-manager.js");
-      const primary = await QmdMemoryManager.create({
-        cfg: params.cfg,
-        agentId: params.agentId,
-        resolved,
-      });
-      if (primary) {
-        const wrapper = new FallbackMemoryManager(
-          {
-            primary,
-            fallbackFactory: async () => {
-              const { MemoryIndexManager } = await import("./manager.js");
-              return await MemoryIndexManager.get(params);
-            },
-          },
-          () => QMD_MANAGER_CACHE.delete(cacheKey),
-        );
-        QMD_MANAGER_CACHE.set(cacheKey, wrapper);
-        return { manager: wrapper };
-      }
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      log.warn(`qmd memory unavailable; falling back to builtin: ${message}`);
-    }
-  }
-
   try {
     const { MemoryIndexManager } = await import("./manager.js");
     const manager = await MemoryIndexManager.get(params);
@@ -63,131 +19,3 @@ export async function getMemorySearchManager(params: {
     return { manager: null, error: message };
   }
 }
-
-class FallbackMemoryManager implements MemorySearchManager {
-  private fallback: MemorySearchManager | null = null;
-  private primaryFailed = false;
-  private lastError?: string;
-
-  constructor(
-    private readonly deps: {
-      primary: MemorySearchManager;
-      fallbackFactory: () => Promise<MemorySearchManager | null>;
-    },
-    private readonly onClose?: () => void,
-  ) {}
-
-  async search(
-    query: string,
-    opts?: { maxResults?: number; minScore?: number; sessionKey?: string },
-  ) {
-    if (!this.primaryFailed) {
-      try {
-        return await this.deps.primary.search(query, opts);
-      } catch (err) {
-        this.primaryFailed = true;
-        this.lastError = err instanceof Error ? err.message : String(err);
-        log.warn(`qmd memory failed; switching to builtin index: ${this.lastError}`);
-        await this.deps.primary.close?.().catch(() => {});
-      }
-    }
-    const fallback = await this.ensureFallback();
-    if (fallback) {
-      return await fallback.search(query, opts);
-    }
-    throw new Error(this.lastError ?? "memory search unavailable");
-  }
-
-  async readFile(params: { relPath: string; from?: number; lines?: number }) {
-    if (!this.primaryFailed) {
-      return await this.deps.primary.readFile(params);
-    }
-    const fallback = await this.ensureFallback();
-    if (fallback) {
-      return await fallback.readFile(params);
-    }
-    throw new Error(this.lastError ?? "memory read unavailable");
-  }
-
-  status() {
-    if (!this.primaryFailed) {
-      return this.deps.primary.status();
-    }
-    const fallbackStatus = this.fallback?.status();
-    const fallbackInfo = { from: "qmd", reason: this.lastError ?? "unknown" };
-    if (fallbackStatus) {
-      const custom = fallbackStatus.custom ?? {};
-      return {
-        ...fallbackStatus,
-        fallback: fallbackInfo,
-        custom: {
-          ...custom,
-          fallback: { disabled: true, reason: this.lastError ?? "unknown" },
-        },
-      };
-    }
-    const primaryStatus = this.deps.primary.status();
-    const custom = primaryStatus.custom ?? {};
-    return {
-      ...primaryStatus,
-      fallback: fallbackInfo,
-      custom: {
-        ...custom,
-        fallback: { disabled: true, reason: this.lastError ?? "unknown" },
-      },
-    };
-  }
-
-  async sync(params?: {
-    reason?: string;
-    force?: boolean;
-    progress?: (update: MemorySyncProgressUpdate) => void;
-  }) {
-    if (!this.primaryFailed) {
-      await this.deps.primary.sync?.(params);
-      return;
-    }
-    const fallback = await this.ensureFallback();
-    await fallback?.sync?.(params);
-  }
-
-  async probeEmbeddingAvailability(): Promise<MemoryEmbeddingProbeResult> {
-    if (!this.primaryFailed) {
-      return await this.deps.primary.probeEmbeddingAvailability();
-    }
-    const fallback = await this.ensureFallback();
-    if (fallback) {
-      return await fallback.probeEmbeddingAvailability();
-    }
-    return { ok: false, error: this.lastError ?? "memory embeddings unavailable" };
-  }
-
-  async probeVectorAvailability() {
-    if (!this.primaryFailed) {
-      return await this.deps.primary.probeVectorAvailability();
-    }
-    const fallback = await this.ensureFallback();
-    return (await fallback?.probeVectorAvailability()) ?? false;
-  }
-
-  async close() {
-    await this.deps.primary.close?.();
-    await this.fallback?.close?.();
-    this.onClose?.();
-  }
-
-  private async ensureFallback(): Promise<MemorySearchManager | null> {
-    if (this.fallback) return this.fallback;
-    const fallback = await this.deps.fallbackFactory();
-    if (!fallback) {
-      log.warn("memory fallback requested but builtin index is unavailable");
-      return null;
-    }
-    this.fallback = fallback;
-    return this.fallback;
-  }
-}
-
-function buildQmdCacheKey(agentId: string, config: ResolvedQmdConfig): string {
-  return `${agentId}:${JSON.stringify(config)}`;
-}

src/memory/session-files.ts

@@ -3,7 +3,6 @@ import path from "node:path";
 
 import { resolveSessionTranscriptsDirForAgent } from "../config/sessions/paths.js";
 import { createSubsystemLogger } from "../logging/subsystem.js";
-import { redactSensitiveText } from "../logging/redact.js";
 import { hashText } from "./internal.js";
 
 const log = createSubsystemLogger("memory");
@@ -88,9 +87,8 @@ export async function buildSessionEntry(absPath: string): Promise<SessionFileEnt
       if (message.role !== "user" && message.role !== "assistant") continue;
       const text = extractSessionText(message.content);
       if (!text) continue;
-      const safe = redactSensitiveText(text, { mode: "tools" });
       const label = message.role === "user" ? "User" : "Assistant";
-      collected.push(`${label}: ${safe}`);
+      collected.push(`${label}: ${text}`);
     }
     const content = collected.join("\n");
     return {

src/memory/sync-memory-files.ts

@@ -14,6 +14,7 @@ type ProgressState = {
 
 export async function syncMemoryFiles(params: {
   workspaceDir: string;
+  extraPaths?: string[];
   db: DatabaseSync;
   needsFullReindex: boolean;
   progress?: ProgressState;
@@ -27,7 +28,7 @@ export async function syncMemoryFiles(params: {
   ftsAvailable: boolean;
   model: string;
 }) {
-  const files = await listMemoryFiles(params.workspaceDir);
+  const files = await listMemoryFiles(params.workspaceDir, params.extraPaths);
   const fileEntries = await Promise.all(
     files.map(async (file) => buildFileEntry(file, params.workspaceDir)),
   );

src/memory/types.ts

@@ -1,79 +0,0 @@
-export type MemorySource = "memory" | "sessions";
-
-export type MemorySearchResult = {
-  path: string;
-  startLine: number;
-  endLine: number;
-  score: number;
-  snippet: string;
-  source: MemorySource;
-  citation?: string;
-};
-
-export type MemoryEmbeddingProbeResult = {
-  ok: boolean;
-  error?: string;
-};
-
-export type MemorySyncProgressUpdate = {
-  completed: number;
-  total: number;
-  label?: string;
-};
-
-export type MemoryProviderStatus = {
-  backend: "builtin" | "qmd";
-  provider: string;
-  model?: string;
-  requestedProvider?: string;
-  files?: number;
-  chunks?: number;
-  dirty?: boolean;
-  workspaceDir?: string;
-  dbPath?: string;
-  sources?: MemorySource[];
-  sourceCounts?: Array<{ source: MemorySource; files: number; chunks: number }>;
-  cache?: { enabled: boolean; entries?: number; maxEntries?: number };
-  fts?: { enabled: boolean; available: boolean; error?: string };
-  fallback?: { from: string; reason?: string };
-  vector?: {
-    enabled: boolean;
-    available?: boolean;
-    extensionPath?: string;
-    loadError?: string;
-    dims?: number;
-  };
-  batch?: {
-    enabled: boolean;
-    failures: number;
-    limit: number;
-    wait: boolean;
-    concurrency: number;
-    pollIntervalMs: number;
-    timeoutMs: number;
-    lastError?: string;
-    lastProvider?: string;
-  };
-  custom?: Record<string, unknown>;
-};
-
-export interface MemorySearchManager {
-  search(
-    query: string,
-    opts?: { maxResults?: number; minScore?: number; sessionKey?: string },
-  ): Promise<MemorySearchResult[]>;
-  readFile(params: {
-    relPath: string;
-    from?: number;
-    lines?: number;
-  }): Promise<{ text: string; path: string }>;
-  status(): MemoryProviderStatus;
-  sync?(params?: {
-    reason?: string;
-    force?: boolean;
-    progress?: (update: MemorySyncProgressUpdate) => void;
-  }): Promise<void>;
-  probeEmbeddingAvailability(): Promise<MemoryEmbeddingProbeResult>;
-  probeVectorAvailability(): Promise<boolean>;
-  close?(): Promise<void>;
-}

src/telegram/bot-message-context.ts

@@ -335,6 +335,7 @@ export const buildTelegramMessageContext = async ({
   let placeholder = "";
   if (msg.photo) placeholder = "<media:image>";
   else if (msg.video) placeholder = "<media:video>";
+  else if (msg.video_note) placeholder = "<media:video>";
   else if (msg.audio || msg.voice) placeholder = "<media:audio>";
   else if (msg.document) placeholder = "<media:document>";
   else if (msg.sticker) placeholder = "<media:sticker>";

src/telegram/bot-native-commands.ts

@@ -468,6 +468,7 @@ export const registerTelegramNativeCommands = ({
             CommandAuthorized: commandAuthorized,
             CommandSource: "native" as const,
             SessionKey: `telegram:slash:${senderId || chatId}`,
+            AccountId: route.accountId,
             CommandTargetSessionKey: sessionKey,
             MessageThreadId: threadIdForSend,
             IsForum: isForum,

src/telegram/bot/delivery.ts

@@ -310,7 +310,14 @@ export async function resolveMedia(
         fetchImpl,
         filePathHint: file.file_path,
       });
-      const saved = await saveMediaBuffer(fetched.buffer, fetched.contentType, "inbound", maxBytes);
+      const originalName = fetched.fileName ?? file.file_path;
+      const saved = await saveMediaBuffer(
+        fetched.buffer,
+        fetched.contentType,
+        "inbound",
+        maxBytes,
+        originalName,
+      );
 
       // Check sticker cache for existing description
       const cached = sticker.file_unique_id ? getCachedSticker(sticker.file_unique_id) : null;
@@ -361,7 +368,12 @@ export async function resolveMedia(
   }
 
   const m =
-    msg.photo?.[msg.photo.length - 1] ?? msg.video ?? msg.document ?? msg.audio ?? msg.voice;
+    msg.photo?.[msg.photo.length - 1] ??
+    msg.video ??
+    msg.video_note ??
+    msg.document ??
+    msg.audio ??
+    msg.voice;
   if (!m?.file_id) return null;
   const file = await ctx.getFile();
   if (!file.file_path) {
@@ -377,10 +389,18 @@ export async function resolveMedia(
     fetchImpl,
     filePathHint: file.file_path,
   });
-  const saved = await saveMediaBuffer(fetched.buffer, fetched.contentType, "inbound", maxBytes);
+  const originalName = fetched.fileName ?? file.file_path;
+  const saved = await saveMediaBuffer(
+    fetched.buffer,
+    fetched.contentType,
+    "inbound",
+    maxBytes,
+    originalName,
+  );
   let placeholder = "<media:document>";
   if (msg.photo) placeholder = "<media:image>";
   else if (msg.video) placeholder = "<media:video>";
+  else if (msg.video_note) placeholder = "<media:video>";
   else if (msg.audio || msg.voice) placeholder = "<media:audio>";
   return { path: saved.path, contentType: saved.contentType, placeholder };
 }

src/telegram/download.ts

@@ -40,7 +40,7 @@ export async function downloadTelegramFile(
     filePath: info.file_path,
   });
   // save with inbound subdir
-  const saved = await saveMediaBuffer(array, mime, "inbound", maxBytes);
+  const saved = await saveMediaBuffer(array, mime, "inbound", maxBytes, info.file_path);
   // Ensure extension matches mime if possible
   if (!saved.contentType && mime) saved.contentType = mime;
   return saved;

src/tts/tts.ts

@@ -757,11 +757,19 @@ export const OPENAI_TTS_MODELS = ["gpt-4o-mini-tts", "tts-1", "tts-1-hd"] as con
  * Custom OpenAI-compatible TTS endpoint.
  * When set, model/voice validation is relaxed to allow non-OpenAI models.
  * Example: OPENAI_TTS_BASE_URL=http://localhost:8880/v1
+ *
+ * Note: Read at runtime (not module load) to support config.env loading.
  */
-const OPENAI_TTS_BASE_URL = (
-  process.env.OPENAI_TTS_BASE_URL?.trim() || "https://api.openai.com/v1"
-).replace(/\/+$/, "");
-const isCustomOpenAIEndpoint = OPENAI_TTS_BASE_URL !== "https://api.openai.com/v1";
+function getOpenAITtsBaseUrl(): string {
+  return (process.env.OPENAI_TTS_BASE_URL?.trim() || "https://api.openai.com/v1").replace(
+    /\/+$/,
+    "",
+  );
+}
+
+function isCustomOpenAIEndpoint(): boolean {
+  return getOpenAITtsBaseUrl() !== "https://api.openai.com/v1";
+}
 export const OPENAI_TTS_VOICES = [
   "alloy",
   "ash",
@@ -778,13 +786,13 @@ type OpenAiTtsVoice = (typeof OPENAI_TTS_VOICES)[number];
 
 function isValidOpenAIModel(model: string): boolean {
   // Allow any model when using custom endpoint (e.g., Kokoro, LocalAI)
-  if (isCustomOpenAIEndpoint) return true;
+  if (isCustomOpenAIEndpoint()) return true;
   return OPENAI_TTS_MODELS.includes(model as (typeof OPENAI_TTS_MODELS)[number]);
 }
 
 function isValidOpenAIVoice(voice: string): voice is OpenAiTtsVoice {
   // Allow any voice when using custom endpoint (e.g., Kokoro Chinese voices)
-  if (isCustomOpenAIEndpoint) return true;
+  if (isCustomOpenAIEndpoint()) return true;
   return OPENAI_TTS_VOICES.includes(voice as OpenAiTtsVoice);
 }
 
@@ -1011,7 +1019,7 @@ async function openaiTTS(params: {
   const timeout = setTimeout(() => controller.abort(), timeoutMs);
 
   try {
-    const response = await fetch(`${OPENAI_TTS_BASE_URL}/audio/speech`, {
+    const response = await fetch(`${getOpenAITtsBaseUrl()}/audio/speech`, {
       method: "POST",
       headers: {
         Authorization: `Bearer ${apiKey}`,

ui/src/ui/app-render.ts

@@ -42,6 +42,7 @@ import { renderNodes } from "./views/nodes";
 import { renderOverview } from "./views/overview";
 import { renderSessions } from "./views/sessions";
 import { renderExecApprovalPrompt } from "./views/exec-approval";
+import { renderGatewayUrlConfirmation } from "./views/gateway-url-confirmation";
 import {
   approveDevicePairing,
   loadDevices,
@@ -578,6 +579,7 @@ export function renderApp(state: AppViewState) {
           : nothing}
       </main>
       ${renderExecApprovalPrompt(state)}
+      ${renderGatewayUrlConfirmation(state)}
     </div>
   `;
 }

ui/src/ui/app-settings.ts

@@ -33,6 +33,7 @@ type SettingsHost = {
   basePath: string;
   themeMedia: MediaQueryList | null;
   themeMediaHandler: ((event: MediaQueryListEvent) => void) | null;
+  pendingGatewayUrl?: string | null;
 };
 
 export function applySettings(host: SettingsHost, next: UiSettings) {
@@ -98,7 +99,7 @@ export function applySettingsFromUrl(host: SettingsHost) {
   if (gatewayUrlRaw != null) {
     const gatewayUrl = gatewayUrlRaw.trim();
     if (gatewayUrl && gatewayUrl !== host.settings.gatewayUrl) {
-      applySettings(host, { ...host.settings, gatewayUrl });
+      host.pendingGatewayUrl = gatewayUrl;
     }
     params.delete("gatewayUrl");
     shouldCleanUrl = true;

ui/src/ui/app-view-state.ts

@@ -73,6 +73,7 @@ export type AppViewState = {
   execApprovalQueue: ExecApprovalRequest[];
   execApprovalBusy: boolean;
   execApprovalError: string | null;
+  pendingGatewayUrl: string | null;
   configLoading: boolean;
   configRaw: string;
   configRawOriginal: string;
@@ -165,6 +166,8 @@ export type AppViewState = {
   handleNostrProfileImport: () => Promise<void>;
   handleNostrProfileToggleAdvanced: () => void;
   handleExecApprovalDecision: (decision: "allow-once" | "allow-always" | "deny") => Promise<void>;
+  handleGatewayUrlConfirm: () => void;
+  handleGatewayUrlCancel: () => void;
   handleConfigLoad: () => Promise<void>;
   handleConfigSave: () => Promise<void>;
   handleConfigApply: () => Promise<void>;

ui/src/ui/app.ts

@@ -152,6 +152,7 @@ export class MoltbotApp extends LitElement {
   @state() execApprovalQueue: ExecApprovalRequest[] = [];
   @state() execApprovalBusy = false;
   @state() execApprovalError: string | null = null;
+  @state() pendingGatewayUrl: string | null = null;
 
   @state() configLoading = false;
   @state() configRaw = "{\n}\n";
@@ -448,6 +449,21 @@ export class MoltbotApp extends LitElement {
     }
   }
 
+  handleGatewayUrlConfirm() {
+    const nextGatewayUrl = this.pendingGatewayUrl;
+    if (!nextGatewayUrl) return;
+    this.pendingGatewayUrl = null;
+    applySettingsInternal(
+      this as unknown as Parameters<typeof applySettingsInternal>[0],
+      { ...this.settings, gatewayUrl: nextGatewayUrl },
+    );
+    this.connect();
+  }
+
+  handleGatewayUrlCancel() {
+    this.pendingGatewayUrl = null;
+  }
+
   // Sidebar handlers for tool output viewing
   handleOpenSidebar(content: string) {
     if (this.sidebarCloseTimer != null) {

ui/src/ui/views/config-form.node.ts

@@ -260,6 +260,11 @@ function renderTextInput(params: {
             }
             onPatch(path, raw);
           }}
+          @change=${(e: Event) => {
+            if (inputType === "number") return;
+            const raw = (e.target as HTMLInputElement).value;
+            onPatch(path, raw.trim());
+          }}
         />
         ${schema.default !== undefined ? html`
           <button

ui/src/ui/views/gateway-url-confirmation.ts

@@ -0,0 +1,39 @@
+import { html, nothing } from "lit";
+
+import type { AppViewState } from "../app-view-state";
+
+export function renderGatewayUrlConfirmation(state: AppViewState) {
+  const { pendingGatewayUrl } = state;
+  if (!pendingGatewayUrl) return nothing;
+
+  return html`
+    <div class="exec-approval-overlay" role="dialog" aria-modal="true" aria-live="polite">
+      <div class="exec-approval-card">
+        <div class="exec-approval-header">
+          <div>
+            <div class="exec-approval-title">Change Gateway URL</div>
+            <div class="exec-approval-sub">This will reconnect to a different gateway server</div>
+          </div>
+        </div>
+        <div class="exec-approval-command mono">${pendingGatewayUrl}</div>
+        <div class="callout danger" style="margin-top: 12px;">
+          Only confirm if you trust this URL. Malicious URLs can compromise your system.
+        </div>
+        <div class="exec-approval-actions">
+          <button
+            class="btn primary"
+            @click=${() => state.handleGatewayUrlConfirm()}
+          >
+            Confirm
+          </button>
+          <button
+            class="btn"
+            @click=${() => state.handleGatewayUrlCancel()}
+          >
+            Cancel
+          </button>
+        </div>
+      </div>
+    </div>
+  `;
+}