@lotargo/memory_plugin 1.6.6 → 1.6.8

package/mcp-server/tools/core/memory_core.js

@@ -30,6 +30,7 @@ import {
   factTitle,
   factBody,
   autoGenerateTitle,
+  isDirectiveFact,
 } from "../../fact_format.js";
 import { requireProjectKey, resolveFactIndex } from "../helpers.js";
 
@@ -71,9 +72,10 @@ async function resolveScopeKey(scope, args = {}, ctx = {}) {
 }
 
 export async function rememberFact(
-  { fact, title, scope, directory, project, docId, startLine, endLine, relationType, ttl, keep, tags, supersedes },
+  { fact, title, kind = "fact", scope, directory, project, docId, startLine, endLine, relationType, ttl, keep, tags, supersedes },
   ctx = {}
 ) {
+  if (!['fact', 'directive'].includes(kind)) throw new Error("kind must be 'fact' or 'directive'.");
   const key = requireProjectKey(await resolveScopeKey(scope, { directory, project }, ctx));
   const entries = await readMemory(key);
 
@@ -87,7 +89,7 @@ export async function rememberFact(
   let supersededInfo = "";
   if (!duplicate) {
     const [date, time] = today().split(" ");
-    const meta = { ttl, tags };
+    const meta = { ttl, tags, kind };
     if (keep) meta.keep = "1";
     if (supersedes) {
       const targetIdx = resolveFactIndex(entries, supersedes);
@@ -109,6 +111,7 @@ export async function rememberFact(
     if (!meta.id) meta.id = nextFactId(entries);
     entries.push(formatFactEntry({ date, time, text, meta }));
     await writeMemory(key, entries);
+    if (key === GLOBAL_KEY && kind === "directive") await syncGlobalPersonaPrompts();
   }
 
   let linkInfo = "";
@@ -189,6 +192,7 @@ export async function recallFacts(
     if (isKeepFact(factLine)) badges.push("KEEP");
     if (isSuperseded(factLine)) badges.push("SUPERSEDED");
     if (meta.inject === "1") badges.push("INJECT");
+    if (isDirectiveFact(factLine)) badges.push("DIRECTIVE");
     if (meta.id) badges.push(`id:${meta.id}`);
     if (meta.tags) badges.push(`tags:${meta.tags}`);
     badges.push(`${p.date} ${p.time}`);
@@ -310,11 +314,13 @@ export async function forgetFacts({ query, scope, force, directory, project }, c
   if (!indices.length) return "Not found.";
 
   const removable = indices.filter((i) => force || !isKeepFact(entries[i]));
+  const removedGlobalDirective = key === GLOBAL_KEY && removable.some((i) => isDirectiveFact(entries[i]));
   const protectedCount = indices.length - removable.length;
   if (removable.length) {
     const removedBodies = removable.map((i) => factBody(entries[i]) || factText(entries[i]));
     for (const i of removable.sort((a, b) => b - a)) entries.splice(i, 1);
     await writeMemory(key, entries);
+    if (removedGlobalDirective) await syncGlobalPersonaPrompts();
     try {
       const { getDatabase } = await import("../../db/database.js");
       const { deleteLinksForFacts } = await import("../../graph/knowledge_linker.js");
@@ -326,7 +332,8 @@ export async function forgetFacts({ query, scope, force, directory, project }, c
   return text;
 }
 
-export async function updateFactText({ id, newText, title, scope, directory, project }, ctx = {}) {
+export async function updateFactText({ id, newText, title, kind, scope, directory, project }, ctx = {}) {
+  if (kind && !['fact', 'directive'].includes(kind)) throw new Error("kind must be 'fact' or 'directive'.");
   const key = requireProjectKey(await resolveScopeKey(scope, { directory, project }, ctx));
   const entries = await readMemory(key);
   const idx = resolveFactIndex(entries, id);
@@ -335,6 +342,7 @@ export async function updateFactText({ id, newText, title, scope, directory, pro
   const p = parseFactEntry(entries[idx]);
   const oldText = p ? p.text : entries[idx];
   const oldBody = factBody(entries[idx]) || oldText;
+  const wasDirective = isDirectiveFact(entries[idx]);
 
   let { finalTitle, finalFact } = splitTitle(newText, title);
   if (!finalTitle) finalTitle = factTitle(entries[idx]) || autoGenerateTitle(finalFact);
@@ -343,9 +351,10 @@ export async function updateFactText({ id, newText, title, scope, directory, pro
     date: p.date,
     time: p.time,
     text: `**${finalTitle}** — ${finalFact}`,
-    meta: p.meta,
+    meta: kind ? { ...p.meta, kind } : p.meta,
   });
   await writeMemory(key, entries);
+  if (key === GLOBAL_KEY && (wasDirective || isDirectiveFact(entries[idx]))) await syncGlobalPersonaPrompts();
 
   let linksUpdated = 0;
   try {
@@ -391,6 +400,17 @@ export async function updateFactText({ id, newText, title, scope, directory, pro
   return `Fact updated${linksUpdated ? `, ${linksUpdated} doc link(s) updated` : ""}`;
 }
 
+async function syncGlobalPersonaPrompts() {
+  if (process.env.MEMORY_DISABLE_PERSONA_SYNC === "1") return;
+  try {
+    const { syncPersonaPrompts } = await import("../../prompt_manager.js");
+    await syncPersonaPrompts();
+  } catch {
+    // Memory persistence must not fail because an optional client config is
+    // unavailable or read-only. Explicit sync-persona surfaces such failures.
+  }
+}
+
 export async function memoryInfo(_args = {}, ctx = {}) {
   const effectiveDir = extractEffectiveDir(_args, ctx) || process.cwd();
   const dbPath = join(MEMORY_DIR, "storage", "memory.sqlite");

package/mcp-server/tools/core/memory_routing.js

@@ -0,0 +1,10 @@
+export const MEMORY_ROUTING_POLICY = `MEMORY ROUTING DIRECTIVE:
+- Use remember for concise durable facts, preferences, constraints, conventions, and decisions that should remain hot and frequently available.
+- Use remember_note for high-value long-form internal memory: decision rationale, investigations, research/experiment results, implementation context, and handoffs that may matter later but should not be auto-injected every session.
+- Use ingest_document for external reusable source material such as files, documentation, codebases, URLs, reports, specifications, and authoritative research sources.
+- Do not save transient conversation noise, routine progress chatter, or disposable intermediate output into either Notebook memory or RAG Memory Notes.
+- Do not duplicate a long note body into remember. When both hot orientation and detailed cold context are useful, save one concise Notebook fact and one detailed RAG Memory Note, then link the fact to the note/document when appropriate.
+- When searching cold memory or knowledge and you first need to identify the right source, prefer query_knowledge_base with resultMode="index", inspect the compact candidates, then expand only the selected doc_id with manage_knowledge_base(action="read_document"). Use resultMode="snippet" when you already want retrieved passage content.`;
+
+export const MEMORY_ROUTING_SHORT =
+  "remember = concise hot durable fact; remember_note = long-form cold internal memory; ingest_document = external reusable source. Avoid transient noise and duplicate hot/cold bodies.";

package/mcp-server/tools/core/note_core.js

@@ -0,0 +1,53 @@
+import { resolveRagScopeKey } from "../../rag_scope.js";
+
+/**
+ * Shared RAG Memory Note implementation used by MCP and native OpenCode surfaces.
+ *
+ * The host agent decides what deserves cold/episodic memory. This helper only
+ * resolves visibility and routes the note through the existing RAG ingestion
+ * pipeline so both tool surfaces keep identical storage semantics.
+ */
+export async function rememberNote(
+  {
+    title,
+    content,
+    scope = "project",
+    kind = "note",
+    tags = null,
+    directory = null,
+    project = null,
+    generateEmbeddings = true,
+  },
+  ctx = {}
+) {
+  const effectiveDirectory = directory || project || ctx.directory || null;
+  const projectScope = await resolveRagScopeKey(scope || "project", {
+    worktree: ctx.worktree ?? null,
+    directory: effectiveDirectory,
+  });
+
+  const { ingestNote } = await import("../../ingest/pipeline.js");
+  const result = await ingestNote({
+    title,
+    content,
+    kind,
+    tags,
+    generateEmbeddings: generateEmbeddings !== false,
+    projectScope,
+  });
+
+  return {
+    status: "success",
+    docId: result.docId,
+    blobHash: result.blobHash,
+    path: result.path,
+    title: result.title,
+    sourceType: result.sourceType,
+    kind: result.kind,
+    tags: result.tags,
+    sectionsCount: result.sectionsCount,
+    microChunksCount: result.microChunksCount,
+    deduplicated: result.deduplicated,
+    scope: result.projectScope,
+  };
+}

package/mcp-server/tools/core/rag_query_core.js

@@ -0,0 +1,169 @@
+import { resolveRagScopeKeys } from "../../rag_scope.js";
+import { getConfig } from "../../config/config_manager.js";
+import { hybridQuery, batchHybridQuery } from "../../retrieval/retriever.js";
+
+function normalizeResultMode(resultMode) {
+  return resultMode === "index" ? "index" : "snippet";
+}
+
+function formatTimestamp(value) {
+  if (value === null || value === undefined || value === "") return null;
+  const numeric = Number(value);
+  const date = Number.isFinite(numeric) ? new Date(numeric) : new Date(value);
+  return Number.isNaN(date.getTime()) ? String(value) : date.toISOString();
+}
+
+async function ensureRagFresh() {
+  if (getConfig().mode !== "hybrid-sync") return;
+  const { ensureReverseSync } = await import("../../db/sync_queue.js");
+  await ensureReverseSync();
+}
+
+function formatIdentityLines(result) {
+  const lines = [];
+  if (result.doc_id) lines.push(`Doc ID: ${result.doc_id}`);
+  if (result.source_type) lines.push(`Source: ${result.source_type}`);
+  if (result.note_kind) lines.push(`Kind: ${result.note_kind}`);
+  if (Array.isArray(result.tags) && result.tags.length > 0) {
+    lines.push(`Tags: ${result.tags.join(", ")}`);
+  }
+  return lines;
+}
+
+export function formatSnippetResult(result, rank, headingLevel = 3) {
+  const hashes = "#".repeat(Math.max(1, headingLevel));
+  let header = `${hashes} [${rank}] ${result.doc_title || "Untitled"}`;
+  if (result.heading) header += ` > ${result.heading}`;
+  if (result.breadcrumbs) header += ` (${result.breadcrumbs})`;
+
+  const bodyLines = [
+    ...formatIdentityLines(result),
+    `Score: ${(result.score || 0).toFixed(4)}`,
+  ];
+
+  if (result.defined_symbols && result.defined_symbols.length > 0) {
+    bodyLines.push(`Defined Symbols: ${result.defined_symbols.join(", ")}`);
+  }
+
+  const body = result.snippet || result.full_section_content || "";
+  return `${header}\n${bodyLines.join("\n")}\n\n${body}`;
+}
+
+export function formatIndexResult(result, rank, headingLevel = 3) {
+  const hashes = "#".repeat(Math.max(1, headingLevel));
+  let header = `${hashes} [${rank}] ${result.doc_title || "Untitled"}`;
+  if (result.heading) header += ` > ${result.heading}`;
+  if (result.breadcrumbs) header += ` (${result.breadcrumbs})`;
+
+  const lines = [
+    ...formatIdentityLines(result),
+    `Score: ${(result.score || 0).toFixed(4)}`,
+  ];
+
+  if (result.retrieval_policy) lines.push(`Policy: ${result.retrieval_policy}`);
+  const createdAt = formatTimestamp(result.doc_created_at);
+  const updatedAt = formatTimestamp(result.doc_updated_at);
+  if (createdAt) lines.push(`Created: ${createdAt}`);
+  if (updatedAt) lines.push(`Updated: ${updatedAt}`);
+
+  return `${header}\n${lines.join("\n")}`;
+}
+
+function formatResult(result, rank, resultMode, headingLevel) {
+  return resultMode === "index"
+    ? formatIndexResult(result, rank, headingLevel)
+    : formatSnippetResult(result, rank, headingLevel);
+}
+
+export async function runSingleRagQuery(
+  {
+    query,
+    limit = 5,
+    instruction = null,
+    generateEmbeddings = true,
+    scope = "all",
+    directory = null,
+    project = null,
+    resultMode = "snippet",
+  },
+  ctx = {}
+) {
+  const mode = normalizeResultMode(resultMode);
+  const activeConfig = getConfig();
+  await ensureRagFresh();
+
+  const effectiveDirectory = directory || project || ctx.directory || null;
+  const scopeKeys = await resolveRagScopeKeys(scope || "all", {
+    worktree: ctx.worktree ?? null,
+    directory: effectiveDirectory,
+  });
+
+  const results = await hybridQuery({
+    query,
+    limit,
+    generateEmbeddings: generateEmbeddings !== false,
+    instruction: instruction || null,
+    scopeKeys,
+    includeGraphContext: mode !== "index",
+    policyExpansion: mode !== "index",
+  });
+
+  if (!results || results.length === 0) {
+    return `[Active Model: ${activeConfig.embeddingModel} | Mode: ${mode}]\nNo matching knowledge found for query.`;
+  }
+
+  const header = `[Active Model: ${activeConfig.embeddingModel} | Fusion: ${activeConfig.fusionAlgorithm.toUpperCase()} | Mode: ${mode}]\n\n`;
+  const formatted = results
+    .map((result, index) => formatResult(result, index + 1, mode, 3))
+    .join("\n\n---\n\n");
+
+  return header + formatted;
+}
+
+export async function runBatchRagQuery(
+  {
+    queries,
+    limit = 5,
+    instruction = null,
+    generateEmbeddings = true,
+    scope = "all",
+    directory = null,
+    project = null,
+    resultMode = "snippet",
+  },
+  ctx = {}
+) {
+  const mode = normalizeResultMode(resultMode);
+  const activeConfig = getConfig();
+  await ensureRagFresh();
+
+  const effectiveDirectory = directory || project || ctx.directory || null;
+  const scopeKeys = await resolveRagScopeKeys(scope || "all", {
+    worktree: ctx.worktree ?? null,
+    directory: effectiveDirectory,
+  });
+
+  const allResults = await batchHybridQuery(queries, {
+    limit,
+    generateEmbeddings: generateEmbeddings !== false,
+    instruction: instruction || null,
+    scopeKeys,
+    includeGraphContext: mode !== "index",
+    policyExpansion: mode !== "index",
+  });
+
+  const formatted = allResults
+    .map((results, queryIndex) => {
+      const queryHeader = `### Query [${queryIndex + 1}]: "${queries[queryIndex]}"\n\n`;
+      if (!results || results.length === 0) {
+        return queryHeader + "No matching knowledge found for this query.";
+      }
+      const items = results
+        .map((result, resultIndex) => formatResult(result, resultIndex + 1, mode, 4))
+        .join("\n\n---\n\n");
+      return queryHeader + items;
+    })
+    .join("\n\n===\n\n");
+
+  return `[Active Model: ${activeConfig.embeddingModel} | Fusion: ${activeConfig.fusionAlgorithm.toUpperCase()} | Mode: ${mode} | ${queries.length} queries]\n\n${formatted}`;
+}

package/mcp-server/tools/index.js

@@ -1,9 +1,11 @@
-import { registerMemoryTools } from "./memory_tools.js";
-import { registerIdentityTools } from "./identity_tools.js";
-import { registerRagTools } from "./rag_tools.js";
-
-export function registerAllTools(server) {
-  registerMemoryTools(server);
-  registerIdentityTools(server);
-  registerRagTools(server);
-}
+import { registerMemoryTools } from "./memory_tools.js";
+import { registerIdentityTools } from "./identity_tools.js";
+import { registerRagTools } from "./rag_tools.js";
+import { registerNoteTools } from "./note_tools.js";
+
+export function registerAllTools(server) {
+  registerMemoryTools(server);
+  registerIdentityTools(server);
+  registerRagTools(server);
+  registerNoteTools(server);
+}

package/mcp-server/tools/memory_tools.js

@@ -16,6 +16,7 @@ export function registerMemoryTools(server) {
       description:
         "Save an important, durable fact to memory. Only use for high-signal information " +
         "(name, goals, constraints, tech preferences, project conventions). " +
+        "Set kind='directive' only for active user-approved personality, behavior, tone, style, preference, or working instructions; use kind='fact' for descriptive context. " +
         "directory: optional workspace/project directory path to target (ensures saving into the project store even from external cwd). " +
         "docId/startLine/endLine/relationType are OPTIONAL and only used to link the fact to a " +
         "Knowledge Base document or line range; omit them when no linking is needed. " +
@@ -29,6 +30,7 @@ export function registerMemoryTools(server) {
       inputSchema: z.object({
         fact: z.string().describe("The fact to remember, written in English"),
         title: optStr().describe("Optional title for the fact. If not specified, one is auto-generated."),
+        kind: z.enum(["fact", "directive"]).nullish().transform((v) => v || "fact").describe("'fact' (context) or 'directive' (active personalization/working instruction)"),
         scope: defStr("project").describe("'project' (default) or 'global'"),
         directory: optStr().describe("Optional workspace/project directory path to target when scope='project' (e.g. 'F:/projects/my-app')"),
         project: optStr().describe("Alias for directory"),
@@ -109,11 +111,12 @@ export function registerMemoryTools(server) {
     {
       description:
         "Update the text of an existing fact by number (from recall), id, or text match, " +
-        "preserving its original date and metadata. Linked Knowledge Base documents are re-pointed to the new text.",
+        "preserving its original date and metadata. kind can optionally reclassify it as context ('fact') or active personalization ('directive'). Linked Knowledge Base documents are re-pointed to the new text.",
       inputSchema: z.object({
         id: z.string().describe("Number (from recall), metadata id, or text of the fact to update"),
         newText: z.string().describe("New fact text"),
         title: optStr().describe("Optional new title for the fact"),
+        kind: z.enum(["fact", "directive"]).nullish().describe("Optional new semantic kind: 'fact' or 'directive'"),
         scope: defStr("project").describe("'project' (default) or 'global'"),
         directory: optStr().describe("Optional workspace/project directory path"),
         project: optStr().describe("Alias for directory"),

package/mcp-server/tools/note_tools.js

@@ -0,0 +1,35 @@
+import * as z from "zod/v4";
+import { optStr, defBool } from "./helpers.js";
+import { rememberNote } from "./core/note_core.js";
+
+const NOTE_KINDS = ["decision", "research", "context", "handoff", "note"];
+
+export function registerNoteTools(server) {
+  server.registerTool(
+    "remember_note",
+    {
+      description:
+        "Save high-value long-form or episodic context as a cold RAG Memory Note. " +
+        "Use this for decisions with rationale, research/experiment results, investigations, handoffs, and detailed context that may matter later but should NOT be injected into every session. " +
+        "Use remember() instead for concise durable facts that should stay hot/automatically available. " +
+        "Use ingest_document() instead for external reusable truth sources such as files, URLs, documentation, reports, or codebases. " +
+        "The note is indexed in the existing RAG knowledge base and can later be found semantically and expanded by document ID.",
+      inputSchema: z.object({
+        title: z.string().trim().min(1).describe("Concise descriptive title for the memory note"),
+        content: z.string().refine((value) => value.trim().length > 0, "RAG Memory Note content must not be empty").describe("Full long-form note content to preserve"),
+        scope: z.enum(["project", "global"]).nullish().transform((v) => v || "project").describe("Visibility: current Git project (default) or global"),
+        kind: z.enum(NOTE_KINDS).catch("note").nullish().transform((v) => v || "note").describe("Note kind: decision, research, context, handoff, or note"),
+        tags: optStr().describe("Optional comma-separated tags; normalized to lowercase unique values"),
+        directory: optStr().describe("Optional workspace/project directory path to target"),
+        project: optStr().describe("Alias for directory"),
+        generateEmbeddings: defBool(true).describe("Compute dense vector embeddings; set false for offline/tests"),
+      }),
+    },
+    async (args) => {
+      const result = await rememberNote(args);
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+      };
+    }
+  );
+}