@lotargo/memory_plugin 1.2.9 → 1.2.902

package/mcp-server/index.js

@@ -32,6 +32,18 @@ const server = new McpServer({
   version: "1.0.0",
 });
 
+// Optional string/number that tolerates null (some tool-call layers fill omitted
+// optional args with null). Linking fields must NEVER be mandatory.
+const optStr = () => z.string().optional().nullable();
+const optNum = () => z.number().optional().nullable();
+const defStr = (fallback) =>
+  z
+    .string()
+    .nullish()
+    .transform((v) => (v === null || v === undefined || v === "" ? fallback : v));
+const defBool = (fallback) => z.boolean().nullish().transform((v) => (v === null || v === undefined ? fallback : v));
+const defNum = (fallback) => z.number().nullish().transform((v) => (v === null || v === undefined ? fallback : v));
+
 // --- Legacy Key-Value Memory Tools ---
 
 // --- Legacy Key-Value Memory Tools & Agent Graph Linking ---
@@ -42,16 +54,17 @@ server.registerTool(
     description:
       "Save an important, durable fact to memory. Only use for high-signal information " +
       "(name, goals, constraints, tech preferences, project conventions). " +
-      "Optionally link the fact to a Knowledge Base document or exact line range (docId, startLine, endLine). " +
+      "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. " +
       "Translate the fact into English and keep it concise. " +
       "scope: 'project' (default) or 'global'",
     inputSchema: z.object({
       fact: z.string().describe("The fact to remember, written in English"),
-      scope: z.string().default("project").describe("'project' (default) or 'global'"),
-      docId: z.string().optional().describe("Optional document ID, title, or path to link this fact to"),
-      startLine: z.number().optional().describe("Optional starting line number in target document"),
-      endLine: z.number().optional().describe("Optional ending line number in target document"),
-      relationType: z.string().default("LINKS_TO").describe("Relation type (e.g. 'RULES_FOR', 'IMPLEMENTS', 'REFERENCES')"),
+      scope: defStr("project").describe("'project' (default) or 'global'"),
+      docId: optStr().describe("Optional document ID, title, or path to link this fact to"),
+      startLine: optNum().describe("Optional starting line number in target document"),
+      endLine: optNum().describe("Optional ending line number in target document"),
+      relationType: defStr("LINKS_TO").describe("Relation type (e.g. 'RULES_FOR', 'IMPLEMENTS', 'REFERENCES')"),
     }),
   },
   async ({ fact, scope, docId, startLine, endLine, relationType }) => {
@@ -97,8 +110,8 @@ server.registerTool(
       "scope: 'project', 'global', 'all' (default), or 'list_projects'. " +
       "Use project: '<directory path>' with scope 'project'/'all' to read facts of a specific project from any working directory.",
     inputSchema: z.object({
-      scope: z.string().default("all").describe("'project', 'global', 'all', or 'list_projects'"),
-      project: z.string().optional().describe("Directory path of the project to read facts from (e.g. 'F:/projects/plugins/memory')"),
+      scope: defStr("all").describe("'project', 'global', 'all', or 'list_projects'"),
+      project: optStr().describe("Directory path of the project to read facts from (e.g. 'F:/projects/plugins/memory')"),
     }),
   },
   async ({ scope, project }) => {
@@ -165,20 +178,30 @@ server.registerTool(
 server.registerTool(
   "forget",
   {
-    description: "Delete a fact by number (from recall) or text search",
+    description:
+      "Delete a fact by number (from recall), by range (e.g. '3-30', inclusive), or by text search",
     inputSchema: z.object({
-      query: z.string().describe("Number or text to search for"),
-      scope: z.string().default("project").describe("'project' (default) or 'global'"),
+      query: z.string().describe("Number, range like '3-30', or text to search for"),
+      scope: defStr("project").describe("'project' (default) or 'global'"),
     }),
   },
   async ({ query, scope }) => {
     const key = scopeKey(scope, null, null);
     const entries = await readMemory(key);
+    const rangeMatch = /^\s*(\d+)\s*-\s*(\d+)\s*$/.exec(query);
     const num = parseInt(query, 10);
     let removed;
-    if (!isNaN(num) && num > 0 && num <= entries.length) {
+    if (rangeMatch) {
+      const from = parseInt(rangeMatch[1], 10);
+      const to = parseInt(rangeMatch[2], 10);
+      if (from > 0 && to >= from && to <= entries.length) {
+        removed = entries.splice(from - 1, to - from + 1);
+      }
+    }
+    if (!removed && !isNaN(num) && num > 0 && num <= entries.length) {
       removed = entries.splice(num - 1, 1);
-    } else {
+    }
+    if (!removed) {
       const filtered = entries.filter((e) => !e.toLowerCase().includes(query.toLowerCase()));
       removed = entries.filter((e) => e.toLowerCase().includes(query.toLowerCase()));
       entries.length = 0;
@@ -197,13 +220,13 @@ server.registerTool(
       "Explicitly link a Notebook memory fact to a Knowledge Base document, section, or line range. " +
       "Creates Agent-driven Graph Edges connecting memory to RAG documents.",
     inputSchema: z.object({
-      action: z.enum(["link", "list_links", "get_doc_links"]).default("link").describe("Action type"),
-      factText: z.string().optional().describe("Memory fact text or keyword"),
-      docId: z.string().optional().describe("Document ID, title, or file path"),
-      scope: z.string().default("project").describe("'project' (default) or 'global'"),
-      startLine: z.number().optional().describe("Starting line number in target document"),
-      endLine: z.number().optional().describe("Ending line number in target document"),
-      relationType: z.string().default("LINKS_TO").describe("Relation type (e.g. 'RULES_FOR', 'IMPLEMENTS', 'EXPLAINS')"),
+      action: z.enum(["link", "list_links", "get_doc_links"]).nullish().transform((v) => v || "link").describe("Action type"),
+      factText: optStr().describe("Memory fact text or keyword"),
+      docId: optStr().describe("Document ID, title, or file path"),
+      scope: defStr("project").describe("'project' (default) or 'global'"),
+      startLine: optNum().describe("Starting line number in target document"),
+      endLine: optNum().describe("Ending line number in target document"),
+      relationType: defStr("LINKS_TO").describe("Relation type (e.g. 'RULES_FOR', 'IMPLEMENTS', 'EXPLAINS')"),
     }),
   },
   async ({ action, factText, docId, scope, startLine, endLine, relationType }) => {
@@ -254,14 +277,15 @@ server.registerTool(
     description:
       "Ingest a document into the RAG knowledge base. " +
       "Accepts local file paths, web URLs, or raw Markdown/text content. " +
+      "For type='url' the page is fetched and its content is indexed (not just the URL). " +
       "Processes document through 3-tier hierarchy chunking (Big/Medium/Small), " +
       "computes dense vectors, and extracts GraphRAG code symbols.",
     inputSchema: z.object({
       content: z.string().describe("Raw text content, file path, or web URL"),
-      type: z.enum(["text", "file", "url"]).default("text").describe("Input content type"),
-      title: z.string().optional().describe("Document title"),
-      path: z.string().optional().describe("Original document file path"),
-      generateEmbeddings: z.boolean().default(true).describe("Compute dense vector embeddings"),
+      type: z.enum(["text", "file", "url"]).nullish().transform((v) => v || "text").describe("Input content type: 'text', 'file', or 'url' (url fetches the page content)"),
+      title: optStr().describe("Document title"),
+      path: optStr().describe("Original document file path"),
+      generateEmbeddings: defBool(true).describe("Compute dense vector embeddings"),
     }),
   },
   async ({ content, type, title, path, generateEmbeddings }) => {
@@ -303,15 +327,12 @@ server.registerTool(
       "Returns top-ranked candidate document sections with breadcrumbs, GraphRAG defined code symbols, and relevance scores.",
     inputSchema: z.object({
       query: z.string().describe("Search query in natural language or symbol name"),
-      limit: z.number().default(5).describe("Maximum number of sections to return"),
-      instruction: z
-        .string()
-        .optional()
-        .describe(
-          "Optional task-specific retrieval instruction shaping embedding focus (e.g. 'Retrieve code snippets', 'Find user preferences'). " +
-          "Recommended when using E5/BGE models for domain-specific queries."
-        ),
-      generateEmbeddings: z.boolean().default(true).describe("Use vector search alongside BM25"),
+      limit: defNum(5).describe("Maximum number of sections to return"),
+      instruction: optStr().describe(
+        "Optional task-specific retrieval instruction shaping embedding focus (e.g. 'Retrieve code snippets', 'Find user preferences'). " +
+        "Recommended when using E5/BGE models for domain-specific queries."
+      ),
+      generateEmbeddings: defBool(true).describe("Use vector search alongside BM25"),
     }),
   },
   async ({ query, limit, instruction, generateEmbeddings }) => {
@@ -364,8 +385,8 @@ server.registerTool(
       "Manage the RAG knowledge base: inspect stats, list documents, read full raw document, delete documents, or export/import snapshots.",
     inputSchema: z.object({
       action: z.enum(["stats", "list", "read_document", "delete", "export_snapshot", "import_snapshot"]).describe("Management action"),
-      docId: z.string().optional().describe("Document ID, title, or path (required for read_document and delete)"),
-      snapshotPath: z.string().optional().describe("File path for snapshot export/import"),
+      docId: optStr().describe("Document ID, title, or path (required for read_document and delete)"),
+      snapshotPath: optStr().describe("File path for snapshot export/import"),
     }),
   },
   async ({ action, docId, snapshotPath }) => {

package/mcp-server/ingest/normalizer.js

@@ -27,6 +27,48 @@ export function cleanHtml(html) {
   return cleaned;
 }
 
+// Fetch a web page and convert it to Markdown/text. Used by the 'url' ingestion type
+// so the RAG store gets the page CONTENT, not just the URL string.
+export async function fetchUrlContent(url) {
+  if (typeof url !== "string" || !/^https?:\/\//i.test(url.trim())) {
+    throw new Error(`Unsupported URL for ingestion: '${url}'. Only http/https URLs are supported.`);
+  }
+  let res;
+  try {
+    res = await fetch(url.trim(), {
+      headers: {
+        "User-Agent": "memory-agent-rag/1.0",
+        Accept: "text/html,application/xhtml+xml,application/json,text/plain,*/*",
+      },
+      redirect: "follow",
+      signal: AbortSignal.timeout(15000),
+    });
+  } catch (err) {
+    throw new Error(`Failed to fetch URL '${url}': ${err.message}`);
+  }
+  if (!res.ok) {
+    throw new Error(`Failed to fetch URL '${url}': HTTP ${res.status} ${res.statusText}`);
+  }
+  const raw = await res.text();
+  const contentType = (res.headers.get("content-type") || "").toLowerCase();
+  const looksLikeHtml = /<html|<body|<div|<article|<main|<!doctype/i.test(raw.slice(0, 4096));
+  let markdown;
+  if (contentType.includes("html") || looksLikeHtml) {
+    markdown = cleanHtml(raw);
+  } else if (contentType.includes("json") || /^[\[{]/.test(raw.trim())) {
+    try {
+      markdown = JSON.stringify(JSON.parse(raw), null, 2);
+    } catch {
+      markdown = raw.trim();
+    }
+  } else {
+    markdown = raw.trim();
+  }
+  const titleMatch = raw.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+  const title = titleMatch ? titleMatch[1].replace(/\s+/g, " ").trim() : null;
+  return { markdown, title: title || null, finalUrl: res.url || url.trim() };
+}
+
 export function extractTitle(markdown, fallbackName = "Untitled Document") {
   const h1Match = markdown.match(/^#\s+(.+)$/m);
   if (h1Match && h1Match[1].trim()) {

package/mcp-server/ingest/pipeline.js

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { getDatabase, BLOBS_DIR } from "../db/database.js";
 import { saveBlob, deleteBlob } from "../storage/blob_store.js";
-import { normalizeContent } from "./normalizer.js";
+import { normalizeContent, fetchUrlContent } from "./normalizer.js";
 import { buildTripleHierarchy } from "./chunker.js";
 import { embedText, embedBatch, vectorToBuffer } from "../ml/model_manager.js";
 import { buildGraphEdges, saveGraphEdges } from "../graph/graph_extractor.js";
@@ -18,13 +18,26 @@ export async function ingestDocument({
 }) {
   const db = customDb || getDatabase();
 
-  const { markdown, title: docTitle, metadata } = normalizeContent({ content, type, path, title });
+  let effectiveType = type;
+  let effectivePath = path;
+  let effectiveTitle = title;
+
+  if (type === "url") {
+    const fetched = await fetchUrlContent(String(content));
+    content = fetched.markdown;
+    effectiveType = "text";
+    effectiveTitle = title || fetched.title;
+    effectivePath = path || fetched.finalUrl || content;
+  }
+
+  const { markdown, title: docTitle, metadata } = normalizeContent({ content, type: effectiveType, path: effectivePath, title: effectiveTitle });
+  if (type === "url") metadata.source_type = "url";
 
   const blobRes = await saveBlob(markdown, customBlobDir);
   const blobHash = blobRes.hash;
 
   const docId = `doc_${randomUUID().replace(/-/g, "").substring(0, 12)}`;
-  const docPath = path || `virtual://${type}/${docId}`;
+  const docPath = effectivePath || `virtual://${type}/${docId}`;
   const now = Date.now();
 
   const hierarchy = buildTripleHierarchy(markdown, docId, docTitle);
@@ -151,6 +164,14 @@ export async function deleteDocument(docIdOrPath, customDb = null, customBlobDir
 
   const microChunks = db.prepare("SELECT id FROM micro_chunks WHERE doc_id = ?").all(doc.id);
 
+  // Collect every id owned by this document so we can purge dangling graph edges
+  // (graph_edges has no FK constraints, so section/chunk/doc references would otherwise leak).
+  const ownedIds = [doc.id];
+  for (const table of ["sections", "medium_chunks", "micro_chunks"]) {
+    const rows = db.prepare(`SELECT id FROM ${table} WHERE doc_id = ?`).all(doc.id);
+    for (const r of rows) ownedIds.push(r.id);
+  }
+
   db.exec("BEGIN IMMEDIATE;");
   try {
     for (const mc of microChunks) {
@@ -159,7 +180,16 @@ export async function deleteDocument(docIdOrPath, customDb = null, customBlobDir
       } catch {}
     }
 
-    db.prepare("DELETE FROM graph_edges WHERE source_id = ? OR target_id = ?").run(doc.id, doc.id);
+    // Auto-clean Agent knowledge graph links pointing at this document.
+    db.prepare("DELETE FROM knowledge_links WHERE doc_id = ?").run(doc.id);
+
+    for (const id of ownedIds) {
+      // GLOB: '*' suffix is exact (unlike LIKE, '_' stays literal in ids like doc_xxx).
+      db.prepare(
+        "DELETE FROM graph_edges WHERE source_id = ? OR target_id = ? OR source_id GLOB ? OR target_id GLOB ?"
+      ).run(id, id, `${id}*`, `${id}*`);
+    }
+
     db.prepare("DELETE FROM documents WHERE id = ?").run(doc.id);
 
     db.exec("COMMIT;");
@@ -175,5 +205,5 @@ export async function deleteDocument(docIdOrPath, customDb = null, customBlobDir
     }
   }
 
-  return { deleted: true, docId: doc.id, title: doc.title };
+  return { deleted: true, docId: doc.id, title: doc.title, linksCleaned: true };
 }

package/opencode-plugin/index.js

@@ -240,7 +240,7 @@ const MCP_SERVERS = [
 
 export const MemoryPlugin = async ({ directory, worktree, client }) => {
   await ensureDir();
-  const projectKey = scopeKey("project", worktree, directory);
+  const activeProjectKey = scopeKey("project", worktree, directory);
 
   return {
     "experimental.chat.messages.transform": async (_input, output) => {
@@ -252,10 +252,10 @@ export const MemoryPlugin = async ({ directory, worktree, client }) => {
 
       const [globalFacts, projectFacts] = await Promise.all([
         readMemoryRaw(GLOBAL_KEY),
-        readMemoryRaw(projectKey),
+        readMemoryRaw(activeProjectKey),
       ]);
 
-      const context = buildMemoryContext(globalFacts, projectFacts, projectKey);
+      const context = buildMemoryContext(globalFacts, projectFacts, activeProjectKey);
       const ref = firstUser.parts[0];
       firstUser.parts.unshift({ ...ref, type: "text", text: context });
     },
@@ -288,7 +288,8 @@ export const MemoryPlugin = async ({ directory, worktree, client }) => {
         description:
           "Save an important, durable fact to memory. Only use for high-signal information " +
           "(name, goals, constraints, tech preferences, project conventions). " +
-          "Optionally link the fact to a Knowledge Base document or exact line range (docId, startLine, endLine). " +
+          "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. " +
           "Translate the fact into English and keep it concise. " +
           "scope: 'project' (default) or 'global'",
         args: {
@@ -415,9 +416,9 @@ export const MemoryPlugin = async ({ directory, worktree, client }) => {
         },
       },
       "forget": {
-        description: "Удалить факт по номеру (см. recall) или тексту",
+        description: "Удалить факт по номеру (см. recall), по диапазону (например '3-30', включительно) или тексту",
         args: {
-          query: { type: "string", description: "Номер факта или текст для поиска" },
+          query: { type: "string", description: "Номер факта, диапазон вида '3-30' или текст для поиска" },
           scope: {
             type: "string",
             description: "project (по умолчанию) или global",
@@ -427,11 +428,20 @@ export const MemoryPlugin = async ({ directory, worktree, client }) => {
         async execute({ query, scope }, { worktree, directory }) {
           const key = scopeKey(scope || "project", worktree, directory);
           const entries = await readMemory(key);
+          const rangeMatch = /^\s*(\d+)\s*-\s*(\d+)\s*$/.exec(query);
           const num = parseInt(query, 10);
           let removed;
-          if (!isNaN(num) && num > 0 && num <= entries.length) {
+          if (rangeMatch) {
+            const from = parseInt(rangeMatch[1], 10);
+            const to = parseInt(rangeMatch[2], 10);
+            if (from > 0 && to >= from && to <= entries.length) {
+              removed = entries.splice(from - 1, to - from + 1);
+            }
+          }
+          if (!removed && !isNaN(num) && num > 0 && num <= entries.length) {
             removed = entries.splice(num - 1, 1);
-          } else {
+          }
+          if (!removed) {
             const filtered = entries.filter((e) => !e.toLowerCase().includes(query.toLowerCase()));
             removed = entries.filter((e) => e.toLowerCase().includes(query.toLowerCase()));
             entries.length = 0;
@@ -502,11 +512,12 @@ export const MemoryPlugin = async ({ directory, worktree, client }) => {
         description:
           "Ingest a document into the RAG knowledge base. " +
           "Accepts local file paths, web URLs, or raw Markdown/text content. " +
+          "For type='url' the page is fetched and its content is indexed (not just the URL). " +
           "Processes document through 3-tier hierarchy chunking (Big/Medium/Small), " +
           "computes dense vectors, and extracts GraphRAG code symbols.",
         args: {
           content: { type: "string", description: "Raw text content, file path, or web URL" },
-          type: { type: "string", description: "Input content type: 'text', 'file', 'url'", default: "text" },
+          type: { type: "string", description: "Input content type: 'text', 'file', 'url' (url fetches the page content)", default: "text" },
           title: { type: "string", description: "Document title" },
           path: { type: "string", description: "Original document file path" },
           generateEmbeddings: { type: "boolean", description: "Compute dense vector embeddings", default: true },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotargo/memory_plugin",
-  "version": "1.2.9",
+  "version": "1.2.902",
   "description": "Persistent memory agent for coding AI tools — remembers user preferences and project context across sessions. Works with Antigravity, OpenCode, Claude Code, and Codex.",
   "type": "module",
   "main": "opencode-plugin/index.js",

package/skills/using-memory/SKILL.md

@@ -59,11 +59,12 @@ Use this tool when adding technical documentation, API specs, architectural docu
 - **Hierarchy Chunking**: The engine automatically creates 3-tier chunks (Big Document -> Medium Section -> Small Micro-Chunk) and extracts GraphRAG code symbols.
 - **Auto Vector Embeddings**: Dense ONNX vectors (`multilingual-e5-small`) are automatically computed and indexed in SQLite.
 - **CRITICAL Schema Usage & Parameters**:
-  - `content` (required, string): Must be the **actual raw text or markdown content** of the document, NOT just a file path!
-  - `type` (optional, enum: `"text"`, `"file"`, `"url"`): Set to `"text"` (default) or `"file"`.
-  - `path` (optional, string): Provide the absolute file path (e.g. `f:\projects\plugins\memory\README.md`).
-  - `title` (optional, string): Provide document title (e.g. `README.md`).
-  - **Correct Example**: `ingest_document(content: "<full text content>", path: "f:/path/to/file.md", title: "file.md", type: "file")`
+  - `content` (required, string): For `type: "text"`/`"file"` it must be the **actual raw text or markdown content** of the document, NOT just a file path! For `type: "url"` it must be the **page URL** — the page is fetched automatically and its content is indexed (not just the URL).
+  - `type` (optional, enum: `"text"`, `"file"`, `"url"`): `"text"` (default), `"file"`, or `"url"` (fetches the web page and indexes its content).
+  - `path` (optional, string): Provide the absolute file path (e.g. `f:\projects\plugins\memory\README.md`). For URLs the final URL is used for deduplication.
+  - `title` (optional, string): Provide document title (e.g. `README.md`). If omitted for a URL, the page `<title>` is used.
+  - **Correct Example (URL)**: `ingest_document(content: "https://docs.example.com/guide", type: "url", title: "Example Guide")`
+  - **Correct Example (text)**: `ingest_document(content: "<full text content>", path: "f:/path/to/file.md", title: "file.md", type: "file")`
   - ❌ **Common Error**: `ingest_document(content: "f:/path/to/file.md")` — this causes validation failures because `content` is missing the text content.
 
 - **CLI/Script Execution Note**: When writing batch node scripts to call `ingestDocument`, remember that `@lotargo/memory_plugin` uses ES Modules (`"type": "module"`). Use `import` syntax instead of `require()`.