@lotargo/memory_plugin 1.6.6 → 1.6.8

package/mcp-server/persona_migration.js

@@ -0,0 +1,39 @@
+import { factMeta, factTitle, isDirectiveFact, withMeta } from "./fact_format.js";
+import { GLOBAL_KEY, readMemory, writeMemory } from "./memory.js";
+import { syncPersonaPrompts } from "./prompt_manager.js";
+
+// Convert compatibility-only persona detection into explicit semantic metadata.
+// Explicit kind values are authoritative and are therefore never changed.
+export function markLegacyPersonaDirectives(entries) {
+  const migrated = [];
+  const nextEntries = entries.map((entry) => {
+    const meta = factMeta(entry);
+    if (meta.kind || !isDirectiveFact(entry)) return entry;
+
+    migrated.push({
+      id: meta.id || null,
+      title: factTitle(entry) || "Untitled directive",
+    });
+    return withMeta(entry, { kind: "directive" });
+  });
+
+  return {
+    entries: nextEntries,
+    migrated,
+    changed: migrated.length,
+  };
+}
+
+export async function migrateLegacyPersonaDirectives({
+  dryRun = false,
+  readGlobal = () => readMemory(GLOBAL_KEY),
+  writeGlobal = (entries) => writeMemory(GLOBAL_KEY, entries),
+  syncPersona = () => syncPersonaPrompts(),
+} = {}) {
+  const result = markLegacyPersonaDirectives(await readGlobal());
+  if (!dryRun) {
+    if (result.changed > 0) await writeGlobal(result.entries);
+    await syncPersona();
+  }
+  return { ...result, dryRun };
+}

package/mcp-server/prompt_manager.js

@@ -1,27 +1,35 @@
-import { readFile, writeFile, mkdir, unlink, rename, copyFile } from "fs/promises";
-import { existsSync } from "fs";
-import { join } from "path";
-import { homedir } from "os";
-import { createHash } from "crypto";
-
-const START_MARKER = "<!-- START MEMORY AGENT PROMPT -->";
-const END_MARKER = "<!-- END MEMORY AGENT PROMPT -->";
-
-export const PROMPT_BLOCK = `${START_MARKER}
-[SYSTEM INSTRUCTION: PERSONAL CONTEXT & MEMORY AGENT]
-1. MANDATORY FIRST STEP (SESSION INITIALIZATION): At the very start of every session or conversation, your VERY FIRST ACTION MUST BE to execute \`recall\` from \`memory-agent\` with \`scope: "all"\` (or without restrictive query filters) to load ALL saved global facts, user preferences, personal context, and project guidelines BEFORE performing any other tasks or reading code. Do NOT filter or restrict the initial \`recall\` call with specific query keywords or scoped parameters, so that no global facts are missed.
-2. PROJECT IDENTITY INITIALIZATION: After the initial recall, call \`memory_info\` for the current workspace. If it reports a Git identity with \`Registry: unlinked\`, immediately call \`link_project_memory\` for the current directory. If linking migrated legacy facts, repeat \`recall(scope: "all")\`. Outside a Git repository, do not create project memory; use global memory only.
-3. PROACTIVE SAVING DIRECTIVE: You MUST automatically and proactively call \`remember\` from \`memory-agent\` whenever the user shares durable facts, personal preferences, coding guidelines, technology choices, or project architecture decisions. Do NOT wait for explicit user commands like "remember this".
-4. SIGNAL FILTER: Save only high-signal facts (name, language, roles, constraints, tech stack preferences, architecture decisions, conventions). Translate facts into clear, concise English when saving. Do NOT save transient details or one-off conversation turns.
-5. QUERY OPTIMIZATION: When using \`query_knowledge_base\` from \`memory-agent\`, transform the user's natural language question into concept-dense search queries. Do NOT send raw conversational questions ("как мне сделать X?", "что такое Y?"). Instead, extract key terms and use concise factual phrases. For multi-part queries or comparisons, use \`batch_query_knowledge_base\` with multiple targeted queries — this is more efficient (single API call, single ONNX inference pass) and yields higher retrieval quality than separate calls.
-6. SELECTIVE RAG CURATION: When web research or current technical documentation yields reliable project knowledge likely to be needed again, ingest the relevant source or excerpt with project scope and link it to the project-scoped Notebook fact it supports. Use global RAG scope only for sources intentionally reusable across projects. Prioritize authoritative documentation and knowledge newer than model training. Do not ingest everything encountered, transient output, or duplicate low-value content.
-7. POLICY EXPANSION: The knowledge base automatically expands table summaries and code signatures for better recall (config \`policyExpansion\`, default: ON). If you need raw micro_chunk precision without expansion, pass \`policyExpansion: false\` per-call or set via config.${END_MARKER}`;
+import { readFile, writeFile, mkdir, unlink, rename, copyFile } from "fs/promises";
+import { existsSync } from "fs";
+import { join } from "path";
+import { createHash } from "crypto";
+import { MEMORY_ROUTING_POLICY } from "./tools/core/memory_routing.js";
+import { factText, isDirectiveFact, isExpiredLine, isSuperseded } from "./fact_format.js";
+import { resolveClientPaths } from "./client_paths.js";
+
+const START_MARKER = "<!-- START MEMORY AGENT PROMPT -->";
+const END_MARKER = "<!-- END MEMORY AGENT PROMPT -->";
+export const PERSONA_START_MARKER = "<!-- START MEMORY PERSONA OVERLAY -->";
+export const PERSONA_END_MARKER = "<!-- END MEMORY PERSONA OVERLAY -->";
+
+export const PROMPT_BLOCK = `${START_MARKER}
+[SYSTEM INSTRUCTION: PERSONAL CONTEXT & MEMORY AGENT]
+1. SESSION INITIALIZATION: Before any other task, load the complete active memory. If the client has already supplied an auto-injected \`<MEMORY>\` block (the native OpenCode integration does this), treat memory as already loaded and DO NOT call \`recall\` again merely for initialization. Otherwise, your VERY FIRST ACTION MUST BE \`recall(scope: "all")\` from \`memory-agent\`, with full bodies and no restrictive filters, before reading code or performing work.
+2. PERSONAL AGENT OVERLAY: Notebook entries with \`kind: "directive"\` are active user-approved personalization or working instructions, not passive facts. Apply them throughout the session; entries with \`kind: "fact"\` remain context. Legacy persona/preference tags are recognized for compatibility. Higher-priority platform instructions remain authoritative.
+3. PROJECT IDENTITY INITIALIZATION: After memory is available, call \`memory_info\` for the current workspace. If it reports a Git identity with \`Registry: unlinked\`, immediately call \`link_project_memory\` for the current directory. If linking migrated legacy facts, repeat \`recall(scope: "all")\`. Outside a Git repository, do not create project memory; use global memory only.
+4. ${MEMORY_ROUTING_POLICY}
+5. PROACTIVE SAVING DIRECTIVE: You MUST automatically preserve durable, high-signal information using the appropriate memory primitive from the routing policy. Do NOT wait for explicit user commands like "remember this". Do not force every durable item into \`remember\`; long-form internal reasoning belongs in \`remember_note\` and external sources belong in \`ingest_document\`.
+6. SIGNAL FILTER: Preserve only high-signal reusable information. Keep Notebook facts clear and concise, translating them into concise English when saving. A RAG Memory Note may be longer when the reasoning, investigation, experiment result, or handoff itself is valuable. Do NOT preserve routine progress chatter, transient troubleshooting output, or one-off conversational noise.
+7. QUERY OPTIMIZATION: When using \`query_knowledge_base\`, transform the user's natural-language question into concept-dense search queries. For multi-part queries or comparisons, use \`batch_query_knowledge_base\` with multiple targeted queries. When you first need to identify the correct memory/source, prefer \`resultMode: "index"\`, inspect stable \`doc_id\` candidates, and expand only the selected item with \`manage_knowledge_base(action: "read_document")\`. Use \`resultMode: "snippet"\` when retrieved passage content is directly needed.
+8. SELECTIVE RAG CURATION: When web research or current technical documentation yields reliable project knowledge likely to be needed again, ingest the relevant source or excerpt with project scope and link it to the project-scoped Notebook fact it supports. Use global RAG scope only for sources intentionally reusable across projects. Prioritize authoritative documentation and knowledge newer than model training. Do not ingest everything encountered, transient output, or duplicate low-value content.
+9. HOT + COLD LINKING: When a decision needs both a concise always-visible orientation point and detailed historical reasoning, save the concise point with \`remember\`, save the detailed record with \`remember_note\`, then connect the Notebook fact to the note using its returned \`docId\` via \`link_knowledge\` (or the optional document-link fields on \`remember\`). Never duplicate the full note body into Notebook memory.
+10. POLICY EXPANSION: The knowledge base automatically expands table summaries and code signatures for content-rich retrieval (config \`policyExpansion\`, default: ON). Semantic TOC/index retrieval disables large policy expansion automatically. If you need raw micro_chunk precision in normal snippet retrieval, pass \`policyExpansion: false\` per-call or set it via config.${END_MARKER}`;
 
 // Plugin-owned files live here so we never destroy user-owned config content.
-const AGENT_CONFIG_DIR = join(homedir(), ".config", "memory-agent");
-export const PROMPT_FILE = join(AGENT_CONFIG_DIR, "prompt.md");
-const BACKUP_DIR = join(AGENT_CONFIG_DIR, "backups");
-const STATE_FILE = join(AGENT_CONFIG_DIR, "prompt-state.json");
+const CLIENT_PATHS = resolveClientPaths();
+const AGENT_CONFIG_DIR = CLIENT_PATHS.agentConfigDir;
+export const PROMPT_FILE = CLIENT_PATHS.promptFile;
+const BACKUP_DIR = CLIENT_PATHS.promptBackupDir;
+const STATE_FILE = CLIENT_PATHS.promptStateFile;
 
 function sha256(content) {
   return createHash("sha256").update(content).digest("hex");
@@ -55,15 +63,21 @@ async function saveState(state) {
   await atomicWrite(STATE_FILE, JSON.stringify(state, null, 2) + "\n");
 }
 
-export function getGlobalPromptTargets() {
-  const home = homedir();
-  return [
-    {
-      name: "Antigravity",
-      filePath: join(home, ".gemini", "config", "AGENTS.md"),
-      // Antigravity resolves `@` imports only in GEMINI.md, not reliably in AGENTS.md
-      includeSupported: false,
-    },
+export function getGlobalPromptTargets() {
+  const { home } = CLIENT_PATHS;
+  return [
+    {
+      name: "Antigravity",
+      filePath: join(home, ".gemini", "config", "AGENTS.md"),
+      // Antigravity resolves `@` imports only in GEMINI.md, not reliably in AGENTS.md
+      includeSupported: false,
+    },
+    {
+      name: "Gemini CLI",
+      filePath: join(home, ".gemini", "GEMINI.md"),
+      // Gemini CLI supports @file imports in its global GEMINI.md context file.
+      includeSupported: true,
+    },
     {
       name: "Codex",
       filePath: join(home, ".codex", "AGENTS.md"),
@@ -95,32 +109,83 @@ function toIncludePath(filePath) {
   return filePath.replace(/\\/g, "/");
 }
 
-function buildIncludeBlock(promptFile) {
+function buildIncludeBlock(promptFile) {
   return `${START_MARKER}
 @${toIncludePath(promptFile)}
 ${END_MARKER}`;
-}
+}
+
+export function activePersonaDirectives(entries, now = Date.now()) {
+  return (entries || []).filter(
+    (entry) => isDirectiveFact(entry) && !isSuperseded(entry) && !isExpiredLine(entry, now)
+  );
+}
+
+export function buildPersonaOverlayBlock(entries, now = Date.now()) {
+  const directives = activePersonaDirectives(entries, now);
+  if (!directives.length) return "";
+  const lines = directives.map((entry, index) => `${index + 1}. ${factText(entry)}`);
+  return `${PERSONA_START_MARKER}
+[PERSONAL AGENT OVERLAY — ACTIVE USER CONFIGURATION]
+The directives below are user-approved persistent instructions for personality, behavior, tone, communication style, preferences, and working conventions. Apply them as instructions rather than merely describing them. Descriptive memory facts are not included here. Higher-priority platform instructions remain authoritative.
+
+${lines.join("\n")}
+${PERSONA_END_MARKER}`;
+}
+
+export function stripPersonaOverlayBlock(content) {
+  return stripManagedBlocks(content, PERSONA_START_MARKER, PERSONA_END_MARKER);
+}
+
+export function upsertPersonaOverlayBlock(content, block) {
+  const clean = stripPersonaOverlayBlock(content).replace(/[\r\n]+$/, "");
+  if (!block) return clean ? `${clean}\n` : "";
+  return clean ? `${clean}\n\n${block}\n` : `${block}\n`;
+}
 
 export function stripPromptBlock(content) {
+  return stripManagedBlocks(content, START_MARKER, END_MARKER);
+}
+
+function stripManagedBlocks(content, startMarker, endMarker) {
   let clean = String(content || "");
   while (true) {
-    const startIndex = clean.indexOf(START_MARKER);
-    const endIndex = clean.indexOf(END_MARKER, startIndex + START_MARKER.length);
+    const startIndex = clean.indexOf(startMarker);
+    const endIndex = clean.indexOf(endMarker, startIndex + startMarker.length);
     if (startIndex === -1 || endIndex === -1 || endIndex <= startIndex) break;
-    clean = clean.substring(0, startIndex) + clean.substring(endIndex + END_MARKER.length);
+    let before = clean.substring(0, startIndex);
+    let after = clean.substring(endIndex + endMarker.length);
+
+    // Remove only the separator newlines inserted around the managed block.
+    // Do not collapse or trim whitespace elsewhere in the user's file.
+    if (after.trim() === "") {
+      before = before.replace(/(?:\r?\n){1,2}$/, "");
+      after = "";
+    } else if (before.trim() === "") {
+      before = "";
+      after = after.replace(/^(?:\r?\n){1,2}/, "");
+    } else {
+      const eol = clean.includes("\r\n") ? "\r\n" : "\n";
+      before = before.replace(/(?:\r?\n){1,2}$/, "");
+      after = after.replace(/^(?:\r?\n){1,2}/, "");
+      before += `${eol}${eol}`;
+    }
+    clean = before + after;
   }
-  return clean.replace(/\r?\n(?:[ \t]*\r?\n){2,}/g, "\n\n").trim();
+  return clean;
 }
-
+
 export function upsertPromptBlock(content, block = PROMPT_BLOCK) {
-  const clean = stripPromptBlock(content);
-  return clean ? `${clean}\n\n${block}\n` : `${block}\n`;
-}
+  const clean = stripPromptBlock(content).replace(/[\r\n]+$/, "");
+  return clean ? `${clean}\n\n${block}\n` : `${block}\n`;
+}
 
 export async function enableGlobalPrompt(targetNames = null) {
   const promptFile = await syncPromptFile();
-  const requested = Array.isArray(targetNames) ? new Set(targetNames) : null;
-  const targets = getGlobalPromptTargets().filter((target) => !requested || requested.has(target.name));
+  const { readMemory, GLOBAL_KEY } = await import("./memory.js");
+  const personaBlock = buildPersonaOverlayBlock(await readMemory(GLOBAL_KEY));
+  const requested = Array.isArray(targetNames) ? new Set(targetNames) : null;
+  const targets = getGlobalPromptTargets().filter((target) => !requested || requested.has(target.name));
   const state = await loadState();
   const results = [];
 
@@ -133,10 +198,10 @@ export async function enableGlobalPrompt(targetNames = null) {
 
       const existed = existsSync(target.filePath);
       const existing = existed ? await readFile(target.filePath, "utf-8") : "";
-      const block = target.includeSupported
-        ? buildIncludeBlock(promptFile)
-        : PROMPT_BLOCK;
-      const updated = upsertPromptBlock(existing, block);
+      const block = target.includeSupported
+        ? buildIncludeBlock(promptFile)
+        : PROMPT_BLOCK;
+      const updated = upsertPersonaOverlayBlock(upsertPromptBlock(existing, block), personaBlock);
 
       const key = target.filePath;
       const prev = state[key];
@@ -168,8 +233,9 @@ export async function enableGlobalPrompt(targetNames = null) {
   return results;
 }
 
-export async function disableGlobalPrompt() {
-  const targets = getGlobalPromptTargets();
+export async function disableGlobalPrompt(targetNames = null) {
+  const requested = Array.isArray(targetNames) ? new Set(targetNames) : null;
+  const targets = getGlobalPromptTargets().filter((target) => !requested || requested.has(target.name));
   const state = await loadState();
   const results = [];
 
@@ -181,12 +247,12 @@ export async function disableGlobalPrompt() {
       }
 
       const existing = await readFile(target.filePath, "utf-8");
-      if (!existing.includes(START_MARKER)) {
+      if (!existing.includes(START_MARKER) && !existing.includes(PERSONA_START_MARKER)) {
         results.push({ name: target.name, filePath: target.filePath, status: "skipped" });
         continue;
       }
 
-      const clean = stripPromptBlock(existing);
+      const clean = stripPersonaOverlayBlock(stripPromptBlock(existing));
       const key = target.filePath;
       const prev = state[key];
 
@@ -212,17 +278,58 @@ export async function disableGlobalPrompt() {
 
   await saveState(state);
   return results;
-}
+}
+
+export async function syncPersonaPrompts(targetNames = null, entries = null) {
+  if (!entries) {
+    const { readMemory, GLOBAL_KEY } = await import("./memory.js");
+    entries = await readMemory(GLOBAL_KEY);
+  }
+  const block = buildPersonaOverlayBlock(entries);
+  const requested = Array.isArray(targetNames) ? new Set(targetNames) : null;
+  const targets = getGlobalPromptTargets().filter((target) => !requested || requested.has(target.name));
+  const state = await loadState();
+  const results = [];
+
+  for (const target of targets) {
+    try {
+      const existed = existsSync(target.filePath);
+      if (!existed && !block) {
+        results.push({ name: target.name, filePath: target.filePath, status: "skipped" });
+        continue;
+      }
+      await mkdir(join(target.filePath, ".."), { recursive: true });
+      const existing = existed ? await readFile(target.filePath, "utf-8") : "";
+      const updated = upsertPersonaOverlayBlock(existing, block);
+      if (existing === updated) {
+        results.push({ name: target.name, filePath: target.filePath, status: "up_to_date" });
+        continue;
+      }
+      const prev = state[target.filePath];
+      if (existed && prev?.hash && prev.hash !== sha256(existing)) await backupFile(target.filePath);
+      await atomicWrite(target.filePath, updated);
+      state[target.filePath] = { hash: sha256(updated), existedBefore: existed };
+      results.push({ name: target.name, filePath: target.filePath, status: block ? "synced" : "removed" });
+    } catch (err) {
+      results.push({ name: target.name, filePath: target.filePath, status: "failed", error: err.message });
+    }
+  }
+
+  await saveState(state);
+  return results;
+}
 
-export async function getGlobalPromptStatus() {
-  const targets = getGlobalPromptTargets();
+export async function getGlobalPromptStatus(targetNames = null) {
+  const requested = Array.isArray(targetNames) ? new Set(targetNames) : null;
+  const targets = getGlobalPromptTargets().filter((target) => !requested || requested.has(target.name));
   const status = [];
 
   for (const target of targets) {
     let enabled = false;
     if (existsSync(target.filePath)) {
       const content = await readFile(target.filePath, "utf-8");
-      enabled = content.includes(START_MARKER) && content.includes(END_MARKER);
+      enabled = (content.includes(START_MARKER) && content.includes(END_MARKER))
+        || (content.includes(PERSONA_START_MARKER) && content.includes(PERSONA_END_MARKER));
     }
     status.push({ name: target.name, filePath: target.filePath, enabled });
   }

package/mcp-server/retrieval/retriever.js

@@ -10,29 +10,51 @@ export function sanitizeFtsQuery(query) {
   return words.join(" OR ");
 }
 
-export async function bm25Search(db, query, limit = 30, scopeKeys = null) {
-  const ftsQuery = sanitizeFtsQuery(query);
-  if (!ftsQuery) return [];
-
-  try {
-    const scoped = Array.isArray(scopeKeys) && scopeKeys.length > 0;
-    const scopeClause = scoped
-      ? `AND EXISTS (
-          SELECT 1 FROM micro_chunks scoped_m
-          JOIN document_scopes scoped_ds ON scoped_ds.doc_id = scoped_m.doc_id
-          WHERE scoped_m.id = micro_chunks_fts.id
-            AND scoped_ds.scope_key IN (${scopeKeys.map(() => "?").join(",")})
-        )`
-      : "";
-    const stmt = db.prepare(`
-      SELECT id, content, breadcrumbs, rank
-      FROM micro_chunks_fts
-      WHERE micro_chunks_fts MATCH ?
-      ${scopeClause}
-      ORDER BY rank
-      LIMIT ?;
-    `);
-    const rows = await stmt.all(ftsQuery, ...(scoped ? scopeKeys : []), limit);
+export function parseDocumentMetadata(value) {
+  if (!value) return {};
+  if (typeof value === "object" && !Array.isArray(value)) return value;
+  if (typeof value !== "string") return {};
+  try {
+    const parsed = JSON.parse(value);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function normalizeRetrievedTags(tags) {
+  if (Array.isArray(tags)) {
+    return [...new Set(tags.map((tag) => String(tag).trim().toLowerCase()).filter(Boolean))].sort();
+  }
+  if (typeof tags === "string") {
+    return [...new Set(tags.split(",").map((tag) => tag.trim().toLowerCase()).filter(Boolean))].sort();
+  }
+  return [];
+}
+
+export async function bm25Search(db, query, limit = 30, scopeKeys = null) {
+  const ftsQuery = sanitizeFtsQuery(query);
+  if (!ftsQuery) return [];
+
+  try {
+    const scoped = Array.isArray(scopeKeys) && scopeKeys.length > 0;
+    const scopeClause = scoped
+      ? `AND EXISTS (
+          SELECT 1 FROM micro_chunks scoped_m
+          JOIN document_scopes scoped_ds ON scoped_ds.doc_id = scoped_m.doc_id
+          WHERE scoped_m.id = micro_chunks_fts.id
+            AND scoped_ds.scope_key IN (${scopeKeys.map(() => "?").join(",")})
+        )`
+      : "";
+    const stmt = db.prepare(`
+      SELECT id, content, breadcrumbs, rank
+      FROM micro_chunks_fts
+      WHERE micro_chunks_fts MATCH ?
+      ${scopeClause}
+      ORDER BY rank
+      LIMIT ?;
+    `);
+    const rows = await stmt.all(ftsQuery, ...(scoped ? scopeKeys : []), limit);
     return rows.map((r, i) => ({
       id: r.id,
       content: r.content,
@@ -60,7 +82,7 @@ export function toVectorBytes(value) {
   return null;
 }
 
-export async function vectorSearch(db, queryVector, limit = 30, minSim = 0.25, scopeKeys = null) {
+export async function vectorSearch(db, queryVector, limit = 30, minSim = 0.25, scopeKeys = null) {
   if (!queryVector || queryVector.length === 0) return [];
 
   const vectorDim = queryVector.length;
@@ -69,32 +91,32 @@ export async function vectorSearch(db, queryVector, limit = 30, minSim = 0.25, s
   const tempVec = new Float32Array(tempBuf);
 
   const scanLimit = Number(getConfig().vectorScanLimit) || 0;
-  const scoped = Array.isArray(scopeKeys) && scopeKeys.length > 0;
-  const scopeClause = scoped
-    ? `WHERE EXISTS (
-        SELECT 1 FROM document_scopes scoped_ds
-        WHERE scoped_ds.doc_id = m.doc_id
-          AND scoped_ds.scope_key IN (${scopeKeys.map(() => "?").join(",")})
-      )`
-    : "";
-  const scanSql = scanLimit > 0
-    ? `
-      SELECT m.id, m.section_id, m.doc_id, m.content, m.vector, s.breadcrumbs
-      FROM micro_chunks m
-      JOIN sections s ON m.section_id = s.id
-      ${scopeClause}
-      LIMIT ?;
-    `
-    : `
-      SELECT m.id, m.section_id, m.doc_id, m.content, m.vector, s.breadcrumbs
-      FROM micro_chunks m
-      JOIN sections s ON m.section_id = s.id
-      ${scopeClause};
-    `;
-
-  const stmt = db.prepare(scanSql);
-  const scopeParams = scoped ? scopeKeys : [];
-  const rows = scanLimit > 0 ? await stmt.all(...scopeParams, scanLimit) : await stmt.all(...scopeParams);
+  const scoped = Array.isArray(scopeKeys) && scopeKeys.length > 0;
+  const scopeClause = scoped
+    ? `WHERE EXISTS (
+        SELECT 1 FROM document_scopes scoped_ds
+        WHERE scoped_ds.doc_id = m.doc_id
+          AND scoped_ds.scope_key IN (${scopeKeys.map(() => "?").join(",")})
+      )`
+    : "";
+  const scanSql = scanLimit > 0
+    ? `
+      SELECT m.id, m.section_id, m.doc_id, m.content, m.vector, s.breadcrumbs
+      FROM micro_chunks m
+      JOIN sections s ON m.section_id = s.id
+      ${scopeClause}
+      LIMIT ?;
+    `
+    : `
+      SELECT m.id, m.section_id, m.doc_id, m.content, m.vector, s.breadcrumbs
+      FROM micro_chunks m
+      JOIN sections s ON m.section_id = s.id
+      ${scopeClause};
+    `;
+
+  const stmt = db.prepare(scanSql);
+  const scopeParams = scoped ? scopeKeys : [];
+  const rows = scanLimit > 0 ? await stmt.all(...scopeParams, scanLimit) : await stmt.all(...scopeParams);
   const scored = [];
   for (const r of rows) {
     // node:sqlite returns BLOBs as plain Uint8Array (NOT Buffer), the Turso
@@ -265,8 +287,8 @@ export async function batchHybridQuery(queries, options = {}) {
     rerankerEnabled = null,
     instruction = null,
     generateEmbeddings = true,
-    policyExpansion = null,
-    scopeKeys = null,
+    policyExpansion = null,
+    scopeKeys = null,
   } = options;
 
   const db = customDb || await getDatabase();
@@ -299,8 +321,8 @@ export async function batchHybridQuery(queries, options = {}) {
         rerankerEnabled: useReranker,
         instruction,
         generateEmbeddings,
-        policyExpansion: usePolicyExpansion,
-        scopeKeys,
+        policyExpansion: usePolicyExpansion,
+        scopeKeys,
         _precomputedVector: queryVectors[i] || null,
       })
     )
@@ -322,8 +344,8 @@ export async function hybridQuery({
   rerankerEnabled = null,
   instruction = null,
   generateEmbeddings = true,
-  policyExpansion = null, // null = use config default
-  scopeKeys = null, // null = all documents; tool surfaces pass global/current-project keys
+  policyExpansion = null, // null = use config default
+  scopeKeys = null, // null = all documents; tool surfaces pass global/current-project keys
   _precomputedVector = null, // internal: skip embedText if batch already computed
 }) {
   const db = customDb || await getDatabase();
@@ -351,28 +373,28 @@ export async function hybridQuery({
   let fusedHits = [];
 
   if (algo === "lexical_only" || algo === "bm25_only") {
-    const bm25Hits = await bm25Search(db, query, limit * 4, scopeKeys);
+    const bm25Hits = await bm25Search(db, query, limit * 4, scopeKeys);
     fusedHits = bm25Hits.map((hit) => ({
       ...hit,
       score: 1.0 / hit.bm25_rank,
     }));
   } else if (algo === "semantic_only" || algo === "vector_only") {
     const queryVector = await getQueryVector();
-    const vectorHits = await vectorSearch(db, queryVector, limit * 4, 0.10, scopeKeys);
+    const vectorHits = await vectorSearch(db, queryVector, limit * 4, 0.10, scopeKeys);
     fusedHits = vectorHits.map((hit) => ({
       ...hit,
       score: hit.cosine_sim,
     }));
   } else if (algo === "rrf") {
-    const bm25Hits = await bm25Search(db, query, 30, scopeKeys);
+    const bm25Hits = await bm25Search(db, query, 30, scopeKeys);
     const queryVector = await getQueryVector();
-    const vectorHits = await vectorSearch(db, queryVector, 30, 0.10, scopeKeys);
+    const vectorHits = await vectorSearch(db, queryVector, 30, 0.10, scopeKeys);
     fusedHits = rrfFusion(bm25Hits, vectorHits, 60, scoreThreshold);
   } else {
     // Default: RSF
-    const bm25Hits = await bm25Search(db, query, 30, scopeKeys);
+    const bm25Hits = await bm25Search(db, query, 30, scopeKeys);
     const queryVector = await getQueryVector();
-    const vectorHits = await vectorSearch(db, queryVector, 30, 0.10, scopeKeys);
+    const vectorHits = await vectorSearch(db, queryVector, 30, 0.10, scopeKeys);
     fusedHits = rsfFusion(bm25Hits, vectorHits, alphaWeight, scoreThreshold);
   }
 
@@ -432,9 +454,11 @@ export async function hybridQuery({
     const topIds = topHits.map((h) => h.id);
     const placeholders = topIds.map(() => "?").join(",");
     const details = await db.prepare(`
-      SELECT m.id as micro_id, m.retrieval_policy, m.policy_source_id,
+      SELECT m.id as micro_id, m.doc_id as doc_id, m.retrieval_policy, m.policy_source_id,
              s.id as section_id, s.heading, s.breadcrumbs, s.content as section_content,
-             med.content as medium_content, d.title as doc_title, d.path as doc_path
+             med.content as medium_content,
+             d.title as doc_title, d.path as doc_path, d.metadata_json,
+             d.created_at as doc_created_at, d.updated_at as doc_updated_at
       FROM micro_chunks m
       JOIN sections s ON m.section_id = s.id
       JOIN documents d ON m.doc_id = d.id
@@ -476,6 +500,10 @@ export async function hybridQuery({
       if (!detail) continue;
 
       const symbols = symbolsBySection.get(detail.section_id) || [];
+      const metadata = parseDocumentMetadata(detail.metadata_json);
+      const sourceType = metadata.source_type || (String(detail.doc_path || "").startsWith("memory://note/") ? "note" : null);
+      const noteKind = sourceType === "note" ? (metadata.note_kind || "note") : null;
+      const tags = normalizeRetrievedTags(metadata.tags);
 
       let snippet = hit.content;
       let paragraphContext = detail.medium_content || hit.content;
@@ -490,8 +518,15 @@ export async function hybridQuery({
 
       results.push({
         chunk_id: hit.id,
+        doc_id: detail.doc_id,
         doc_title: detail.doc_title,
         doc_path: detail.doc_path,
+        source_type: sourceType,
+        note_kind: noteKind,
+        tags,
+        metadata,
+        doc_created_at: detail.doc_created_at ?? null,
+        doc_updated_at: detail.doc_updated_at ?? null,
         heading: detail.heading,
         breadcrumbs: detail.breadcrumbs,
         snippet,