@lotargo/memory_plugin 1.2.901 → 1.3.0

package/opencode-plugin/index.js

@@ -3,6 +3,32 @@ const { existsSync } = await import("fs");
 const { join, basename, dirname, resolve } = await import("path");
 const { homedir } = await import("os");
 const { fileURLToPath } = await import("url");
+const {
+  parseFactEntry,
+  factText,
+  factMeta,
+  withMeta,
+  nextFactId,
+  isKeepFact,
+  isSuperseded,
+  displayFact,
+  formatFactEntry,
+  matchesQuery,
+  matchesTags,
+  inDateRange,
+} = await import("../mcp-server/fact_format.js");
+
+// Resolve a fact reference (1-based number, metadata id, or text) to an index.
+function resolveFactIndex(entries, ref) {
+  const trimmed = String(ref || "").trim();
+  if (!trimmed) return -1;
+  const num = parseInt(trimmed, 10);
+  if (/^\d+$/.test(trimmed) && num >= 1 && num <= entries.length) return num - 1;
+  const idIdx = entries.findIndex((e) => factMeta(e).id === trimmed);
+  if (idIdx !== -1) return idIdx;
+  const textIdx = entries.findIndex((e) => factText(e).toLowerCase().includes(trimmed.toLowerCase()));
+  return textIdx;
+}
 
 const CONFIG_DIR = process.env.OPENCODE_CONFIG_DIR || join(homedir(), ".config", "opencode");
 const MEMORY_DIR = join(CONFIG_DIR, "memory");
@@ -214,13 +240,18 @@ const MEMORY_INSTRUCTION =
   "When saving, translate the fact into clear, concise English.\n" +
   "Use `scope: \"global\"` for personal facts, `scope: \"project\"` for project-specific facts.";
 
-function buildMemoryContext(globalFacts, projectFacts, projectKey) {
+function buildMemoryContext(globalFacts, projectFacts, projectKey, now = Date.now()) {
   const parts = [MEMORY_INSTRUCTION];
+  const fmt = (entries) =>
+    entries
+      .filter((e) => !isSuperseded(e))
+      .map((e, i) => `${i + 1}. ${displayFact(e, now)}`)
+      .join("\n");
   if (globalFacts.length) {
-    parts.push("## Global\n" + globalFacts.map((f, i) => `${i + 1}. ${f}`).join("\n"));
+    parts.push("## Global\n" + fmt(globalFacts));
   }
   if (projectFacts.length) {
-    parts.push(`## Project: ${projectKey}\n` + projectFacts.map((f, i) => `${i + 1}. ${f}`).join("\n"));
+    parts.push(`## Project: ${projectKey}\n` + fmt(projectFacts));
   }
   return `<MEMORY>\n${parts.join("\n\n")}\n</MEMORY>`;
 }
@@ -240,7 +271,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) => {
@@ -251,11 +282,11 @@ export const MemoryPlugin = async ({ directory, worktree, client }) => {
       if (firstUser.parts.some((p) => p.type === "text" && p.text.includes("<MEMORY>"))) return;
 
       const [globalFacts, projectFacts] = await Promise.all([
-        readMemoryRaw(GLOBAL_KEY),
-        readMemoryRaw(projectKey),
+        readMemory(GLOBAL_KEY),
+        readMemory(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 +319,12 @@ 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. " +
+          "ttl is OPTIONAL (e.g. '90d', '2w', '24h') — expired facts are shown with [EXPIRED] but not auto-deleted. " +
+          "keep=true protects the fact from forget deletion unless force=true. " +
+          "tags is OPTIONAL comma-separated text for filtering. " +
+          "supersedes is OPTIONAL: a number, id, or text of a fact this one replaces. " +
           "Translate the fact into English and keep it concise. " +
           "scope: 'project' (default) or 'global'",
         args: {
@@ -306,16 +342,38 @@ export const MemoryPlugin = async ({ directory, worktree, client }) => {
             description: "Relation type (e.g. 'RULES_FOR', 'IMPLEMENTS', 'REFERENCES')",
             default: "LINKS_TO",
           },
+          ttl: { type: "string", description: "Optional time-to-live, e.g. '90d', '2w', '24h', '12m'" },
+          keep: { type: "boolean", description: "Protect the fact from forget deletion unless force=true" },
+          tags: { type: "string", description: "Optional comma-separated tags, e.g. 'pref,arch'" },
+          supersedes: { type: "string", description: "Optional number, id, or text of the fact this one replaces" },
         },
-        async execute({ fact, scope, docId, startLine, endLine, relationType }, { worktree, directory }) {
+        async execute({ fact, scope, docId, startLine, endLine, relationType, ttl, keep, tags, supersedes }, { worktree, directory }) {
           const key = scopeKey(scope || "project", worktree, directory);
           const entries = await readMemory(key);
           const factNormalized = fact.toLowerCase().trim();
-          if (!entries.some((e) => {
-            const idx = e.indexOf("] ");
-            return idx !== -1 && e.slice(idx + 2).toLowerCase().trim() === factNormalized;
-          })) {
-            entries.push(`- [${today()}] ${fact}`);
+          const duplicate = entries.some((e) => factText(e).toLowerCase().trim() === factNormalized);
+
+          let supersededInfo = "";
+          if (!duplicate) {
+            const [date, time] = today().split(" ");
+            const meta = { ttl, tags };
+            if (keep) meta.keep = "1";
+            if (supersedes) {
+              const targetIdx = resolveFactIndex(entries, supersedes);
+              if (targetIdx !== -1) {
+                const newId = nextFactId(entries);
+                const targetMeta = factMeta(entries[targetIdx]);
+                const targetId = targetMeta.id || nextFactId(entries);
+                entries[targetIdx] = withMeta(entries[targetIdx], { id: targetId, supersededBy: newId });
+                meta.id = newId;
+                meta.supersedes = targetId;
+                supersededInfo = ` [superseded: "${factText(entries[targetIdx]).slice(0, 60)}"]`;
+              } else {
+                supersededInfo = " (note: supersedes target not found)";
+              }
+            }
+            if (!meta.id) meta.id = nextFactId(entries);
+            entries.push(formatFactEntry({ date, time, text: fact, meta }));
             await writeMemory(key, entries);
           }
 
@@ -338,15 +396,18 @@ export const MemoryPlugin = async ({ directory, worktree, client }) => {
             }
           }
 
-          await notify(client, "Memory updated" + linkInfo);
-          return "Memory updated" + linkInfo;
+          const result = "Memory updated" + supersededInfo + linkInfo;
+          await notify(client, result);
+          return result;
         },
       },
       "recall": {
         description:
           "Show saved facts with any Agent-linked Knowledge Base documents/lines. " +
           "scope: 'project', 'global', 'all' (default), or 'list_projects'. " +
-          "Use project: '<directory path>' to read facts of a specific project from any working directory.",
+          "Use project: '<directory path>' to read facts of a specific project from any working directory. " +
+          "query filters by keyword, tags by comma-separated tags, since/until by date (YYYY-MM-DD). " +
+          "The response includes the store file paths.",
         args: {
           scope: {
             type: "string",
@@ -354,8 +415,12 @@ export const MemoryPlugin = async ({ directory, worktree, client }) => {
             default: "all",
           },
           project: { type: "string", description: "Directory path of the project to read facts from (e.g. 'F:/projects/plugins/memory')" },
+          query: { type: "string", description: "Optional keyword filter; all space-separated terms must match" },
+          tags: { type: "string", description: "Optional comma-separated tag filter (any match)" },
+          since: { type: "string", description: "Optional start date filter, YYYY-MM-DD (inclusive)" },
+          until: { type: "string", description: "Optional end date filter, YYYY-MM-DD (inclusive)" },
         },
-        async execute({ scope, project }, { worktree, directory }) {
+        async execute({ scope, project, query, tags, since, until }, { worktree, directory }) {
           const results = [];
 
           let getLinksForFact;
@@ -364,11 +429,11 @@ export const MemoryPlugin = async ({ directory, worktree, client }) => {
             getLinksForFact = linker.getLinksForFact;
           } catch (e) {}
 
-          const formatFactWithLinks = (factText, key) => {
-            let line = factText;
+          const formatFactWithLinks = (factLine, key) => {
+            let line = displayFact(factLine);
             if (getLinksForFact) {
               try {
-                const links = getLinksForFact(key, factText);
+                const links = getLinksForFact(key, factText(factLine));
                 if (links && links.length > 0) {
                   const docStr = links
                     .map((l) => {
@@ -383,39 +448,45 @@ export const MemoryPlugin = async ({ directory, worktree, client }) => {
             return line;
           };
 
+          const target = project ? canonicalPath(project) : projectKey(worktree, directory);
+          const label = project ? target : projectName(worktree, directory);
+
+          const collect = (entries, key) => {
+            const matched = entries.filter(
+              (e) => matchesQuery(e, query) && matchesTags(e, tags) && inDateRange(e, since, until)
+            );
+            if (!matched.length) return;
+            if (results.length) results.push("");
+            results.push(`--- ${key === GLOBAL_KEY ? "Global" : `Project: ${key === target ? label : key}`} ---`);
+            matched.forEach((e, i) => results.push(`${i + 1}. ${formatFactWithLinks(e, key)}`));
+            results.push(`Store file: ${memoryPath(key)}`);
+          };
+
           if (scope === "list_projects") {
             return listProjectStores().then((stores) => {
               if (!stores.length) return "No project memory stores found.";
               const lines = stores.map(
                 (s, i) => `${i + 1}. ${s.basename} — ${s.count} fact(s) [${s.file}]${s.path ? ` (bound to ${s.path})` : " (unbound legacy store)"}`
               );
-              return `Project Memory Stores:\n${lines.join("\n")}\n\nUse recall(scope: "project", project: "<path>") to read a specific store.`;
+              return `Project Memory Stores:\n${lines.join("\n")}\n\nUse recall(scope: "project", project: "<path>") to read a specific store.\n\nMemory dir: ${MEMORY_DIR}`;
             });
           }
 
-          const target = project ? canonicalPath(project) : projectKey(worktree, directory);
-          const label = project ? target : projectName(worktree, directory);
-
           if (scope !== "project") {
-            const global = await readMemoryRaw(GLOBAL_KEY);
-            if (global.length) {
-              results.push("--- Global ---");
-              global.forEach((e, i) => results.push(`${i + 1}. ${formatFactWithLinks(e, GLOBAL_KEY)}`));
-            }
+            const global = await readMemory(GLOBAL_KEY);
+            collect(global, GLOBAL_KEY);
           }
           if (scope !== "global") {
-            const local = await readMemoryRaw(target);
-            if (local.length) {
-              if (results.length) results.push("");
-              results.push(`--- Project: ${label} ---`);
-              local.forEach((e, i) => results.push(`${i + 1}. ${formatFactWithLinks(e, target)}`));
-            }
+            const local = await readMemory(target);
+            collect(local, target);
           }
-          return results.length ? results.join("\n") : "Memory is empty.";
+          const filtered = Boolean(query || tags || since || until);
+          if (!results.length) return filtered ? "No facts match the search." : "Memory is empty.";
+          return results.join("\n") + `\n\nMemory dir: ${MEMORY_DIR}`;
         },
       },
       "forget": {
-        description: "Удалить факт по номеру (см. recall), по диапазону (например '3-30', включительно) или тексту",
+        description: "Удалить факт по номеру (см. recall), по диапазону (например '3-30', включительно) или тексту. Защищённые факты (remember с keep=true) пропускаются, если не передан force=true",
         args: {
           query: { type: "string", description: "Номер факта, диапазон вида '3-30' или текст для поиска" },
           scope: {
@@ -423,35 +494,118 @@ export const MemoryPlugin = async ({ directory, worktree, client }) => {
             description: "project (по умолчанию) или global",
             default: "project",
           },
+          force: { type: "boolean", description: "Удалить также защищённые (keep) факты" },
         },
-        async execute({ query, scope }, { worktree, directory }) {
+        async execute({ query, scope, force }, { 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;
+          let indices = [];
           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);
+              for (let i = from - 1; i < to; i++) indices.push(i);
             }
           }
-          if (!removed && !isNaN(num) && num > 0 && num <= entries.length) {
-            removed = entries.splice(num - 1, 1);
+          if (!indices.length && !isNaN(num) && num > 0 && num <= entries.length) {
+            indices.push(num - 1);
+          }
+          if (!indices.length) {
+            const q = query.toLowerCase();
+            indices = entries.reduce((acc, e, i) => (e.toLowerCase().includes(q) ? acc.concat(i) : acc), []);
           }
-          if (!removed) {
-            const filtered = entries.filter((e) => !e.toLowerCase().includes(query.toLowerCase()));
-            removed = entries.filter((e) => e.toLowerCase().includes(query.toLowerCase()));
-            entries.length = 0;
-            entries.push(...filtered);
+          if (!indices.length) return "Not found.";
+
+          const removable = indices.filter((i) => force || !isKeepFact(entries[i]));
+          const protectedCount = indices.length - removable.length;
+          if (removable.length) {
+            for (const i of removable.sort((a, b) => b - a)) entries.splice(i, 1);
+            await writeMemory(key, entries);
           }
+          let result = removable.length ? "Memory updated" : "Nothing removed.";
+          if (protectedCount) result += ` (${protectedCount} protected fact(s) skipped; use force=true to override)`;
+          if (removable.length) await notify(client, result);
+          return result;
+        },
+      },
+      "update_fact": {
+        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.",
+        args: {
+          id: { type: "string", description: "Number (from recall), metadata id, or text of the fact to update" },
+          newText: { type: "string", description: "New fact text" },
+          scope: { type: "string", description: "'project' (default) or 'global'", default: "project" },
+        },
+        async execute({ id, newText, scope }, { worktree, directory }) {
+          const key = scopeKey(scope || "project", worktree, directory);
+          const entries = await readMemory(key);
+          const idx = resolveFactIndex(entries, id);
+          if (idx === -1) throw new Error(`Fact not found: ${id}`);
+          const p = parseFactEntry(entries[idx]);
+          const oldText = p ? p.text : entries[idx];
+          const newLine = formatFactEntry({ date: p.date, time: p.time, text: newText, meta: p.meta });
+          entries[idx] = newLine;
           await writeMemory(key, entries);
-          const result = removed.length ? "Memory updated" : "Not found.";
-          if (removed.length) await notify(client, "Memory updated");
+
+          let linksUpdated = 0;
+          try {
+            const { getDatabase } = await import("../mcp-server/db/database.js");
+            const db = getDatabase();
+            const res = db
+              .prepare("UPDATE knowledge_links SET fact_text = ? WHERE fact_key = ? AND fact_text = ?")
+              .run(newText, key, oldText);
+            linksUpdated = res.changes;
+          } catch (e) {}
+
+          const result = `Fact updated${linksUpdated ? `, ${linksUpdated} doc link(s) updated` : ""}`;
+          await notify(client, result);
           return result;
         },
       },
+      "memory_info": {
+        description: "Show memory storage paths (store files, MEMORY_DIR, SQLite DB), fact counts, and Knowledge Base stats.",
+        args: {},
+        async execute() {
+          const dbPath = join(MEMORY_DIR, "storage", "memory.sqlite");
+          let version = "unknown";
+          try {
+            const { readFile } = await import("fs/promises");
+            version = JSON.parse(
+              await readFile(new URL("../package.json", import.meta.url), "utf-8")
+            ).version;
+          } catch (e) {}
+
+          let rag = {};
+          try {
+            const { getDatabase } = await import("../mcp-server/db/database.js");
+            const db = getDatabase();
+            rag.documents = db.prepare("SELECT COUNT(*) AS c FROM documents").get().c;
+            rag.sections = db.prepare("SELECT COUNT(*) AS c FROM sections").get().c;
+            rag.chunks = db.prepare("SELECT COUNT(*) AS c FROM micro_chunks").get().c;
+            rag.edges = db.prepare("SELECT COUNT(*) AS c FROM graph_edges").get().c;
+            rag.links = db.prepare("SELECT COUNT(*) AS c FROM knowledge_links").get().c;
+          } catch (e) {
+            rag.error = e.message;
+          }
+
+          const lines = [
+            `Version: ${version}`,
+            `MEMORY_DIR: ${MEMORY_DIR}`,
+            `SQLite DB: ${dbPath}`,
+            `Global store: ${memoryPath(GLOBAL_KEY)}`,
+            `Project store: ${memoryPath(activeProjectKey)}`,
+          ];
+          if (rag.error) lines.push(`RAG: unavailable (${rag.error})`);
+          else
+            lines.push(
+              `RAG: ${rag.documents} doc(s), ${rag.sections} section(s), ${rag.chunks} chunk(s), ${rag.edges} edge(s), ${rag.links} memory link(s)`
+            );
+          return lines.join("\n");
+        },
+      },
       "link_knowledge": {
         description:
           "Explicitly link a Notebook memory fact to a Knowledge Base document, section, or line range. " +
@@ -511,11 +665,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.901",
+  "version": "1.3.0",
   "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",
@@ -25,6 +25,7 @@
     "mcp-server/storage",
     "mcp-server/cli.js",
     "mcp-server/index.js",
+    "mcp-server/fact_format.js",
     "mcp-server/memory.js",
     "mcp-server/setup.js",
     "mcp-server/preinstall.js",

package/skills/using-memory/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: using-memory
-description: Comprehensive guide for using the Memory & Hybrid RAG Knowledge Engine tools (remember, recall, forget, link_knowledge, ingest_document, query_knowledge_base, manage_knowledge_base). Trigger proactively whenever user preferences, project conventions, technology stack choices, or architecture decisions are introduced, or when querying ingested documentation, indexing files/repos, or managing persistent knowledge.
+description: Comprehensive guide for using the Memory & Hybrid RAG Knowledge Engine tools (remember, recall, forget, update_fact, memory_info, link_knowledge, ingest_document, query_knowledge_base, manage_knowledge_base). Trigger proactively whenever user preferences, project conventions, technology stack choices, or architecture decisions are introduced, or when querying ingested documentation, indexing files/repos, or managing persistent knowledge.
 ---
 
 # Using Memory & Hybrid RAG Knowledge Engine
@@ -17,8 +17,13 @@ You have access to a persistent dual-layer memory engine supercharged with an **
 | Scenario / Intent | Target Tool | Key Parameters |
 |-------------------|-------------|----------------|
 | User shares identity, tech stack preference, or workflow rule | `remember` | `fact` (English), `scope`, optional `docId`, `startLine`, `endLine` |
-| User asks what you remember about them, the project, or linked docs | `recall` | `scope` ("all", "global", or "project") |
-| User corrects/updates an old saved fact | `forget` then `remember` | `query` (text or index number) |
+| User asks what you remember about them, the project, or linked docs | `recall` | `scope` ("all", "global", or "project"), optional `query`, `tags`, `since`, `until`, `project` |
+| User corrects/updates an old saved fact | `update_fact` | `id` (number/id/text), `newText`, `scope` |
+| Replace a fact but keep a version trail | `remember` | `fact`, `supersedes` (number/id/text) |
+| Protect a fact from accidental `forget` | `remember` | `keep: true` |
+| Set a time-to-live on a fact | `remember` | `ttl` ("90d", "2w", "24h", "12m") |
+| Filter facts by keyword / tags / date | `recall` | `query`, `tags`, `since`, `until` |
+| Show storage paths, versions, fact & RAG stats | `memory_info` | — |
 | Connect a Notebook fact to a document, section, or line range | `link_knowledge` | `factText`, `docId`, `startLine`, `endLine`, `relationType` |
 | User asks to index a documentation URL, file, or repository | `ingest_document` | `content` or `source_path`, `title`, `metadata` |
 | User asks a complex question about indexed docs or code | `query_knowledge_base` | `query`, `limit`, `generateEmbeddings` |
@@ -27,7 +32,7 @@ You have access to a persistent dual-layer memory engine supercharged with an **
 
 ---
 
-## 2. Layer 1 & 3: Notebook Store & Agent-Driven Knowledge Graph (`remember`, `recall`, `link_knowledge`)
+## 2. Layer 1 & 3: Notebook Store & Agent-Driven Knowledge Graph (`remember`, `recall`, `update_fact`, `forget`, `memory_info`, `link_knowledge`)
 
 ### Agent-Driven Knowledge Graph Architecture
 Automatic regex/heuristic algorithms alone CANNOT infer high-level semantic intent or cross-document relationships. **You (the AI Agent) are the primary architect of the Knowledge Graph.**
@@ -50,6 +55,43 @@ When `recall` is invoked, the engine returns saved facts along with their Agent-
 2. PostgreSQL 16 is primary database 🔗 [Linked Docs: database_guide.md:L20-35]
 ```
 
+### Fact Line Format & Metadata
+Each fact is stored as a single Markdown line with an optional invisible HTML comment carrying metadata:
+```
+- [2026-08-02 06:08] user prefers TypeScript <!-- id:8f3a2c, ttl:90d, keep:1, tags:pref,arch -->
+```
+Supported metadata keys (set via `remember`, rendered as badges by `recall`):
+- `id` — auto-generated short id; stable reference for `update_fact` / `forget` / `supersedes`.
+- `ttl` — time-to-live ("90d", "2w", "24h", "12m", bare number = days). Expired facts are marked `[EXPIRED]` but never auto-deleted.
+- `keep` — protection flag; `forget` skips it unless `force: true`.
+- `tags` — comma-separated free-form tags for filtering.
+- `supersedes` / `supersededBy` — versioning: the old fact gets `[SUPERSEDED]` and is excluded from the injected memory block while staying in the store for history.
+
+### Remember Options (`remember`)
+- `ttl`: "90d", "2w", "24h", "12m" — mark the fact for expiry; it will show `[EXPIRED]` once past.
+- `keep: true`: protect the fact from `forget` (unless `force: true`).
+- `tags`: comma-separated tags for later filtering, e.g. `"pref,arch"`.
+- `supersedes`: number (as listed by `recall`), metadata `id`, or text of the fact this one replaces.
+
+### Filtering Facts (`recall`)
+- `query`: all space-separated terms must match (case-insensitive); searches text, id, tags, and date.
+- `tags`: comma-separated; returns facts with ANY matching tag.
+- `since` / `until`: "YYYY-MM-DD" (inclusive) to filter by fact date.
+- `project`: read a specific project's store from any working directory.
+- Output shows `[EXPIRED]`, `[KEEP]`, `[SUPERSEDED]` badges and the `Store file:` path.
+
+### Updating Facts (`update_fact`)
+When the user corrects an old fact, prefer `update_fact` over `forget`+`remember` — it rewrites the text while preserving the original date and all metadata (`ttl`, `keep`, `tags`, `supersedes`), and re-points any linked Knowledge Base documents.
+- `id`: recall index number, metadata `id`, or text of the fact.
+- `newText`: replacement text.
+- `scope`: "project" (default) or "global".
+
+### Protecting Facts (`forget` with `keep`)
+`forget` refuses to delete facts saved with `keep: true`; pass `force: true` to override. It still supports deleting by index number, range ("3-30"), or text.
+
+### Storage Diagnostics (`memory_info`)
+`memory_info` returns the package version, `MEMORY_DIR`, SQLite DB path, store-file locations, fact counts per store, and RAG stats (documents, sections, chunks, graph edges, links).
+
 ---
 
 ## 3. Layer 2: RAG Knowledge Base (`ingest_document`, `query_knowledge_base`, `manage_knowledge_base`)
@@ -59,11 +101,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()`.
@@ -120,4 +163,4 @@ In such cases, use the **Full Raw Document Reading** mechanism:
 2. **Be Proactive**: When the user mentions a durable preference, personal fact, or constraint, save it immediately using `remember`. Do not wait for explicit user commands.
 3. **Check Knowledge Base First**: If a user asks how a specific module, API, or project architecture works, call `query_knowledge_base` using concept-dense search phrases.
 4. **Inspect Ambiguous Docs Directly**: If querying produces low relevance scores on abstractly-named documents, call `manage_knowledge_base(action: "read_document")` to inspect the full text directly.
-5. **Keep Memory Clean**: If a preference changes, call `forget` on the outdated entry before saving the new one.
+5. **Keep Memory Clean**: If a preference changes, call `update_fact` to edit it in place, or `remember` with `supersedes` to keep a version trail. Use `keep: true` for facts that must survive an accidental `forget`, and give ephemeral facts a `ttl` so stale ones surface as `[EXPIRED]`.