feat (memory): Implement new (opt-in) QMD memory backend

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

@@ -0,0 +1,65 @@
+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,12 @@
 import { Type } from "@sinclair/typebox";
-import type { OpenClawConfig } from "../../config/config.js";
-import type { AnyAgentTool } from "./common.js";
+
+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";
 import { jsonResult, readNumberParam, readStringParam } from "./common.js";
 
 const MemorySearchSchema = Type.Object({
@@ -19,20 +22,16 @@ const MemoryGetSchema = Type.Object({
 });
 
 export function createMemorySearchTool(options: {
-  config?: OpenClawConfig;
+  config?: MoltbotConfig;
   agentSessionKey?: string;
 }): AnyAgentTool | null {
   const cfg = options.config;
-  if (!cfg) {
-    return null;
-  }
+  if (!cfg) return null;
   const agentId = resolveSessionAgentId({
     sessionKey: options.agentSessionKey,
     config: cfg,
   });
-  if (!resolveMemorySearchConfig(cfg, agentId)) {
-    return null;
-  }
+  if (!resolveMemorySearchConfig(cfg, agentId)) return null;
   return {
     label: "Memory Search",
     name: "memory_search",
@@ -51,17 +50,21 @@ export function createMemorySearchTool(options: {
         return jsonResult({ results: [], disabled: true, error });
       }
       try {
-        const results = await manager.search(query, {
+        const citationsMode = resolveMemoryCitationsMode(cfg);
+        const includeCitations = citationsMode !== "off";
+        const rawResults = 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);
@@ -72,25 +75,21 @@ export function createMemorySearchTool(options: {
 }
 
 export function createMemoryGetTool(options: {
-  config?: OpenClawConfig;
+  config?: MoltbotConfig;
   agentSessionKey?: string;
 }): AnyAgentTool | null {
   const cfg = options.config;
-  if (!cfg) {
-    return null;
-  }
+  if (!cfg) return null;
   const agentId = resolveSessionAgentId({
     sessionKey: options.agentSessionKey,
     config: cfg,
   });
-  if (!resolveMemorySearchConfig(cfg, agentId)) {
-    return null;
-  }
+  if (!resolveMemorySearchConfig(cfg, agentId)) return null;
   return {
     label: "Memory Get",
     name: "memory_get",
     description:
-      "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.",
+      "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.",
     parameters: MemoryGetSchema,
     execute: async (_toolCallId, params) => {
       const relPath = readStringParam(params, "path", { required: true });
@@ -117,3 +116,28 @@ 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}`;
+}