@lotargo/memory_plugin 1.2.902 → 1.3.0

package/mcp-server/cli.js

@@ -6,6 +6,7 @@ import { hybridQuery } from "./retrieval/retriever.js";
 import { getDatabase } from "./db/database.js";
 import { deleteDocument } from "./ingest/pipeline.js";
 import { readMemoryRaw, readMemory, writeMemory, GLOBAL_KEY, projectName, projectKey, listProjectStores, migrateLegacyStore, memoryFileName } from "./memory.js";
+import { parseFactEntry, factText, withMeta, displayFact, nextFactId, isKeepFact, isSuperseded, formatFactEntry, metaBadges } from "./fact_format.js";
 import { getCorpusCacheSize, clearCorpusCache } from "./benchmarks/fetch_real_corpus.js";
 import { SMOKE_DOC_IDS } from "./benchmarks/quality_evaluator.js";
 import { getModelStorageInfo, deleteModelCache, listAllCachedModels } from "./ml/model_manager.js";
@@ -628,6 +629,16 @@ function waitForEnter() {
   });
 }
 
+function promptText(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(`\n  ${question}\n  > `, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
 export async function runCli() {
   const cliArgs = process.argv.slice(2);
   if (cliArgs.includes("--enable-prompt") || cliArgs.includes("enable-prompt")) {
@@ -1035,11 +1046,15 @@ export async function runCli() {
               }
 
               const file = memoryFileName(key);
-              const factItems = factList.map((fact, idx) => ({
-                label: `${idx + 1}. ${fact}`,
-                value: idx,
-                info: `Select to delete this fact from ${file}`,
-              }));
+              const factItems = factList.map((fact, idx) => {
+                const badges = metaBadges(fact);
+                return {
+                  label: `${idx + 1}. ${factText(fact)}`,
+                  value: idx,
+                  badge: badges.length ? badges.join(" ") : undefined,
+                  info: `Select to manage this fact from ${file}`,
+                };
+              });
               factItems.push({ label: "< Back", value: "back" });
 
               const factRes = await selectSimpleMenu({
@@ -1053,22 +1068,58 @@ export async function runCli() {
               }
 
               const selectedIdx = factRes.value;
-              const selectedFact = factList[selectedIdx];
+              const selectedEntry = rawEntries[selectedIdx];
+              const selDisplay = displayFact(selectedEntry);
+              const selBadges = metaBadges(selectedEntry);
+
+              const actionItems = [
+                { label: "[UPDATE] Edit fact text", value: "update", info: "Rewrite the fact, keeping its date and metadata" },
+              ];
+              if (isKeepFact(selectedEntry)) {
+                actionItems.push({ label: "[UNPROTECT] Remove keep protection", value: "unprotect", info: "Allow forget to delete it without force" });
+              } else {
+                actionItems.push({ label: "[PROTECT] Mark as important (keep)", value: "protect", info: "forget will skip it unless force=true" });
+              }
+              actionItems.push({ label: "[DELETE] Delete this fact from store", value: "delete", info: "Remove fact permanently" });
+              actionItems.push({ label: "< Cancel / Back", value: "cancel" });
 
               const actionRes = await selectSimpleMenu({
-                title: `FACT ACTION`,
-                subtitle: `Fact: "${selectedFact}"`,
-                items: [
-                  { label: "[DELETE] Delete this fact from store", value: "delete", info: "Remove fact permanently" },
-                  { label: "< Cancel / Back", value: "cancel" },
-                ],
+                title: "FACT ACTION",
+                subtitle: `Fact: "${selDisplay}"${selBadges.length ? " [" + selBadges.join("] [") + "]" : ""}`,
+                items: actionItems,
               });
 
               if (actionRes.action === "back" || actionRes.value === "cancel") {
                 return;
               }
 
-              if (actionRes.action === "select" && actionRes.value === "delete") {
+              if (actionRes.action === "select" && actionRes.value === "update") {
+                const p = parseFactEntry(selectedEntry);
+                const newText = await promptText(`New text for fact #${selectedIdx + 1}:`);
+                if (!newText) continue;
+                const newLine = formatFactEntry({ date: p.date, time: p.time, text: newText, meta: p.meta });
+                const updated = [...rawEntries];
+                updated[selectedIdx] = newLine;
+                await writeMemory(key, updated);
+                let links = 0;
+                try {
+                  const db = getDatabase();
+                  links = db
+                    .prepare("UPDATE knowledge_links SET fact_text = ? WHERE fact_key = ? AND fact_text = ?")
+                    .run(newText, key, factText(selectedEntry)).changes;
+                } catch (e) {}
+                console.clear();
+                console.log(`\n  [OK] Fact updated successfully${links ? `, ${links} doc link(s) updated` : ""}.\n`);
+                await waitForEnter();
+              } else if (actionRes.action === "select" && (actionRes.value === "protect" || actionRes.value === "unprotect")) {
+                const updated = [...rawEntries];
+                updated[selectedIdx] =
+                  actionRes.value === "protect" ? withMeta(selectedEntry, { keep: "1" }) : withMeta(selectedEntry, { keep: null });
+                await writeMemory(key, updated);
+                console.clear();
+                console.log(`\n  [OK] Fact ${actionRes.value === "protect" ? "protected" : "unprotected"} successfully.\n`);
+                await waitForEnter();
+              } else if (actionRes.action === "select" && actionRes.value === "delete") {
                 const updated = [...rawEntries];
                 updated.splice(selectedIdx, 1);
                 await writeMemory(key, updated);

package/mcp-server/fact_format.js

@@ -0,0 +1,177 @@
+// Shared fact-line format + metadata parsing for the Notebook Layer 1 store.
+//
+// A fact line looks like:
+//   - [2026-08-02 06:08] text here <!-- id:8f3a2c, ttl:90d, keep:1, supersedes:a1b2c3, tags:pref,arch -->
+// The trailing HTML comment carries optional metadata. It is invisible in
+// Markdown, so the store stays a single plain Markdown file. Older lines
+// without a comment parse to empty metadata and stay fully compatible.
+//
+// Metadata keys:
+//   id           short random id (e.g. "8f3a2c")
+//   ttl          time-to-live, e.g. "90d", "2w", "24h", "12m" (m=month ~30d)
+//   keep         "1" = protected fact: forget refuses to delete without force
+//   supersedes   id (or number/text) this fact replaces
+//   supersededBy id of the fact that replaced this one
+//   tags         comma-separated free-form tags for recall filtering
+
+const META_KEYS = ["id", "ttl", "keep", "supersedes", "supersededBy", "tags"];
+
+const ENTRY_RE = /^- \[(\d{4}-\d{2}-\d{2})\s+(\d{2}:\d{2})\]\s+(.*)$/;
+
+// Parse a raw entry line into { line, date, time, text, meta }.
+// Returns null if the line is not a fact entry.
+export function parseFactEntry(line) {
+  const m = ENTRY_RE.exec(line);
+  if (!m) return null;
+  const [, date, time, rest] = m;
+  let text = rest;
+  const meta = {};
+  const cm = /^(.*?)\s*<!--\s*(.*?)\s*-->$/.exec(rest);
+  if (cm) {
+    // Values may themselves contain commas (e.g. "tags:pref,arch"), so scan
+    // for known "key:" tokens instead of splitting the comment on commas.
+    const raw = cm[2];
+    const keyRe = new RegExp(`(${META_KEYS.join("|")})\\s*:`, "g");
+    const found = [];
+    let fm;
+    while ((fm = keyRe.exec(raw))) {
+      found.push({ key: fm[1], valStart: fm.index + fm[0].length, tokenStart: fm.index });
+    }
+    for (let i = 0; i < found.length; i++) {
+      const valEnd = i + 1 < found.length ? found[i + 1].tokenStart : raw.length;
+      const v = raw.slice(found[i].valStart, valEnd).replace(/[,\s]+$/, "").trim();
+      if (v !== "") {
+        meta[found[i].key] = v;
+      }
+    }
+    if (Object.keys(meta).length) text = cm[1];
+  }
+  return { line, date, time, text, meta };
+}
+
+// Display text of a fact line (metadata comment stripped).
+export function factText(line) {
+  const p = parseFactEntry(line);
+  return p ? p.text : line;
+}
+
+// Metadata object of a fact line (empty if none / unparsable).
+export function factMeta(line) {
+  const p = parseFactEntry(line);
+  return p ? p.meta : {};
+}
+
+// Format a fact line from parts. `meta` entries with falsy values are omitted.
+export function formatFactEntry({ date, time, text, meta = {} }) {
+  let out = `- [${date} ${time}] ${text}`;
+  const pairs = [];
+  for (const k of META_KEYS) {
+    if (meta[k]) pairs.push(`${k}:${meta[k]}`);
+  }
+  if (pairs.length) out += ` <!-- ${pairs.join(", ")} -->`;
+  return out;
+}
+
+// Return a new line with `patch` applied to the metadata. Patch values that are
+// null/undefined/"" remove the corresponding key. Non-fact lines are returned
+// unchanged.
+export function withMeta(line, patch) {
+  const p = parseFactEntry(line);
+  if (!p) return line;
+  const meta = { ...p.meta };
+  for (const k of Object.keys(patch)) {
+    const v = patch[k];
+    if (v === null || v === undefined || v === "") delete meta[k];
+    else meta[k] = String(v);
+  }
+  return formatFactEntry({ date: p.date, time: p.time, text: p.text, meta });
+}
+
+// Generate a short random id that is unique within the given entries.
+export function nextFactId(entries) {
+  let id;
+  do {
+    id = Math.random().toString(36).slice(2, 8);
+  } while (entries.some((e) => factMeta(e).id === id));
+  return id;
+}
+
+const TTL_UNITS = { h: 3600e3, d: 86400e3, w: 7 * 86400e3, m: 30 * 86400e3 };
+
+// Parse "90d" | "2w" | "24h" | "12m" (m = ~30 days) into milliseconds. Null if invalid.
+export function ttlMs(ttl) {
+  const m = /^(\d+)\s*([hdwm])?$/.exec(String(ttl || "").trim());
+  if (!m) return null;
+  const n = parseInt(m[1], 10);
+  const u = m[2] || "d";
+  return n * (TTL_UNITS[u] || TTL_UNITS.d);
+}
+
+// True if the fact line has a ttl and it has elapsed relative to `now` (ms).
+export function isExpiredLine(line, now = Date.now()) {
+  const p = parseFactEntry(line);
+  if (!p || !p.meta.ttl) return false;
+  const ms = ttlMs(p.meta.ttl);
+  if (!ms) return false;
+  const ts = new Date(`${p.date}T${p.time}:00`).getTime();
+  if (Number.isNaN(ts)) return false;
+  return now > ts + ms;
+}
+
+// True if the fact is protected from deletion (keep:1).
+export function isKeepFact(line) {
+  return factMeta(line).keep === "1";
+}
+
+// True if the fact has been superseded by another fact.
+export function isSuperseded(line) {
+  return Boolean(factMeta(line).supersededBy);
+}
+
+// Keyword match: space-separated terms, all must be present (case-insensitive).
+// Also matches against the fact's id and tags.
+export function matchesQuery(factLine, query) {
+  const q = String(query || "").trim();
+  if (!q) return true;
+  const p = parseFactEntry(factLine);
+  if (!p) return false;
+  const terms = q.toLowerCase().split(/\s+/).filter(Boolean);
+  const haystack = `${p.text} ${p.meta.id || ""} ${p.meta.tags || ""} ${p.date}`.toLowerCase();
+  return terms.every((t) => haystack.includes(t));
+}
+
+// Tag filter: comma-separated requested tags; match if ANY fact tag equals or
+// contains a requested tag (case-insensitive).
+export function matchesTags(factLine, tagsStr) {
+  const want = String(tagsStr || "").split(",").map((t) => t.trim().toLowerCase()).filter(Boolean);
+  if (!want.length) return true;
+  const have = (factMeta(factLine).tags || "").split(",").map((t) => t.trim().toLowerCase()).filter(Boolean);
+  if (!have.length) return false;
+  return want.some((w) => have.some((h) => h === w || h.includes(w) || w.includes(h)));
+}
+
+// Date-range filter. `since`/`until` are "YYYY-MM-DD" (inclusive).
+export function inDateRange(factLine, since, until) {
+  const p = parseFactEntry(factLine);
+  if (!p) return false;
+  if (since && p.date < since) return false;
+  if (until && p.date > until) return false;
+  return true;
+}
+
+// Human-readable badges for a fact line, e.g. ["EXPIRED", "KEEP", "SUPERSEDED"].
+export function metaBadges(factLine, now = Date.now()) {
+  const badges = [];
+  if (isExpiredLine(factLine, now)) badges.push("EXPIRED");
+  if (isKeepFact(factLine)) badges.push("KEEP");
+  if (isSuperseded(factLine)) badges.push("SUPERSEDED");
+  return badges;
+}
+
+// Display text of a fact line with badges appended, e.g.
+//   "user prefers TS  [EXPIRED] [KEEP]"
+export function displayFact(factLine, now = Date.now()) {
+  const text = factText(factLine);
+  const badges = metaBadges(factLine, now);
+  return badges.length ? `${text}  [${badges.join("] [")}]` : text;
+}

package/mcp-server/index.js

@@ -2,7 +2,34 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import * as z from "zod/v4";
-import { ensureDir, readMemory, readMemoryRaw, writeMemory, today, MEMORY_DIR, GLOBAL_KEY, scopeKey, projectKey, projectName, canonicalPath, listProjectStores } from "./memory.js";
+import { ensureDir, readMemory, readMemoryRaw, writeMemory, today, MEMORY_DIR, GLOBAL_KEY, scopeKey, projectKey, projectName, canonicalPath, listProjectStores, storeFilePath } from "./memory.js";
+import {
+  parseFactEntry,
+  factText,
+  factMeta,
+  withMeta,
+  nextFactId,
+  isKeepFact,
+  displayFact,
+  formatFactEntry,
+  matchesQuery,
+  matchesTags,
+  inDateRange,
+} from "./fact_format.js";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+// 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 cliArgs = process.argv.slice(2);
 
@@ -56,6 +83,11 @@ server.registerTool(
       "(name, goals, constraints, tech preferences, project conventions). " +
       "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 (from recall), id, or text of a fact this one replaces; " +
+      "the target is then marked [SUPERSEDED]. " +
       "Translate the fact into English and keep it concise. " +
       "scope: 'project' (default) or 'global'",
     inputSchema: z.object({
@@ -65,17 +97,42 @@ server.registerTool(
       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')"),
+      ttl: optStr().describe("Optional time-to-live, e.g. '90d', '2w', '24h', '12m'"),
+      keep: defBool(false).describe("Protect the fact from forget deletion unless force=true"),
+      tags: optStr().describe("Optional comma-separated tags, e.g. 'pref,arch'"),
+      supersedes: optStr().describe("Optional number, id, or text of the fact this one replaces"),
     }),
   },
-  async ({ fact, scope, docId, startLine, endLine, relationType }) => {
+  async ({ fact, scope, docId, startLine, endLine, relationType, ttl, keep, tags, supersedes }) => {
     const key = scopeKey(scope, null, null);
     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}`);
+    let duplicate = false;
+    if (entries.some((e) => factText(e).toLowerCase().trim() === factNormalized)) {
+      duplicate = true;
+    }
+
+    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);
     }
 
@@ -98,7 +155,7 @@ server.registerTool(
       }
     }
 
-    return { content: [{ type: "text", text: `Memory updated${linkInfo}` }] };
+    return { content: [{ type: "text", text: `Memory updated${supersededInfo}${linkInfo}` }] };
   }
 );
 
@@ -108,20 +165,27 @@ server.registerTool(
     description:
       "Show saved facts with any Agent-linked Knowledge Base documents/lines. " +
       "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.",
+      "Use project: '<directory path>' with scope 'project'/'all' to read facts of a specific project from any working directory. " +
+      "query filters by keyword (all space-separated terms must match). " +
+      "tags filters by comma-separated tags. since/until filter by date (YYYY-MM-DD, inclusive). " +
+      "Expired facts are shown with [EXPIRED], protected ones with [KEEP]. The response includes the store file paths.",
     inputSchema: z.object({
       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')"),
+      query: optStr().describe("Optional keyword filter; all space-separated terms must match"),
+      tags: optStr().describe("Optional comma-separated tag filter (any match)"),
+      since: optStr().describe("Optional start date filter, YYYY-MM-DD (inclusive)"),
+      until: optStr().describe("Optional end date filter, YYYY-MM-DD (inclusive)"),
     }),
   },
-  async ({ scope, project }) => {
+  async ({ scope, project, query, tags, since, until }) => {
     const { getLinksForFact } = await import("./graph/knowledge_linker.js");
     const results = [];
 
-    const formatFactWithLinks = (factText, key) => {
-      let line = factText;
+    const formatFactWithLinks = (factLine, key) => {
+      let line = displayFact(factLine);
       try {
-        const links = getLinksForFact(key, factText);
+        const links = getLinksForFact(key, factText(factLine));
         if (links && links.length > 0) {
           const docStr = links
             .map((l) => {
@@ -135,6 +199,17 @@ server.registerTool(
       return line;
     };
 
+    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: ${storeFilePath(key)}`);
+    };
+
     if (scope === "list_projects") {
       const stores = await listProjectStores();
       if (!stores.length) {
@@ -147,7 +222,7 @@ server.registerTool(
         content: [
           {
             type: "text",
-            text: `Project Memory Stores:\n${lines.join("\n")}\n\nUse recall(scope: "project", project: "<path>") to read a specific store.`,
+            text: `Project Memory Stores:\n${lines.join("\n")}\n\nUse recall(scope: "project", project: "<path>") to read a specific store.\n\nMemory dir: ${MEMORY_DIR}`,
           },
         ],
       };
@@ -156,21 +231,19 @@ server.registerTool(
     const target = project ? canonicalPath(project) : projectKey(null, null);
     const label = project ? target : projectName();
     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);
     }
-    const text = results.length ? results.join("\n") : "Memory is empty.";
+    const filtered = Boolean(query || tags || since || until);
+    const text = results.length
+      ? `${results.join("\n")}\n\nMemory dir: ${MEMORY_DIR}`
+      : filtered
+        ? "No facts match the search."
+        : "Memory is empty.";
     return { content: [{ type: "text", text }] };
   }
 );
@@ -179,40 +252,143 @@ server.registerTool(
   "forget",
   {
     description:
-      "Delete a fact by number (from recall), by range (e.g. '3-30', inclusive), or by text search",
+      "Delete a fact by number (from recall), by range (e.g. '3-30', inclusive), or by text search. " +
+      "Protected facts (remember with keep=true) are skipped unless force=true.",
     inputSchema: z.object({
       query: z.string().describe("Number, range like '3-30', or text to search for"),
       scope: defStr("project").describe("'project' (default) or 'global'"),
+      force: defBool(false).describe("Also delete protected (keep) facts"),
     }),
   },
-  async ({ query, scope }) => {
+  async ({ query, scope, force }) => {
     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;
+    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 (!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) {
+      const q = query.toLowerCase();
+      indices = entries.reduce((acc, e, i) => (e.toLowerCase().includes(q) ? acc.concat(i) : acc), []);
     }
-    await writeMemory(key, entries);
-    const text = removed.length ? "Memory updated" : "Not found.";
+    if (!indices.length) {
+      return { content: [{ type: "text", text: "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 text = removable.length ? "Memory updated" : "Nothing removed.";
+    if (protectedCount) text += ` (${protectedCount} protected fact(s) skipped; use force=true to override)`;
     return { content: [{ type: "text", text }] };
   }
 );
 
+server.registerTool(
+  "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.",
+    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"),
+      scope: defStr("project").describe("'project' (default) or 'global'"),
+    }),
+  },
+  async ({ id, newText, scope }) => {
+    const key = scopeKey(scope, null, null);
+    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);
+
+    let linksUpdated = 0;
+    try {
+      const { getDatabase } = await import("./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) {}
+
+    return {
+      content: [
+        { type: "text", text: `Fact updated${linksUpdated ? `, ${linksUpdated} doc link(s) updated` : ""}` },
+      ],
+    };
+  }
+);
+
+server.registerTool(
+  "memory_info",
+  {
+    description:
+      "Show memory storage paths (store file locations, MEMORY_DIR, SQLite DB), fact counts, " +
+      "Knowledge Base stats, and the installed package version.",
+    inputSchema: z.object({}),
+  },
+  async () => {
+    const dbPath = join(MEMORY_DIR, "storage", "memory.sqlite");
+    const globalFile = storeFilePath(GLOBAL_KEY);
+    const projectFile = storeFilePath(projectKey(null, null));
+
+    let version = "unknown";
+    try {
+      version = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf-8")).version;
+    } catch (e) {}
+
+    let rag = {};
+    try {
+      const { getDatabase } = await import("./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 stores = await listProjectStores();
+    const lines = [
+      `Version: ${version}`,
+      `MEMORY_DIR: ${MEMORY_DIR}`,
+      `SQLite DB: ${dbPath}`,
+      `Global store: ${globalFile}`,
+      `Project store: ${projectFile}`,
+      `Project stores: ${stores.length}`,
+      `Facts (global): ${(await readMemoryRaw(GLOBAL_KEY)).length}`,
+      `Facts (project): ${(await readMemoryRaw(projectKey(null, null))).length}`,
+    ];
+    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 { content: [{ type: "text", text: lines.join("\n") }] };
+  }
+);
+
 server.registerTool(
   "link_knowledge",
   {

package/mcp-server/memory.js

@@ -72,6 +72,10 @@ export function memoryFileName(key) {
   return basename(memoryPath(key));
 }
 
+export function storeFilePath(key) {
+  return memoryPath(key);
+}
+
 function parseMeta(content) {
   const m = content.match(/<!-- path: (.+?) -->/);
   return { path: m ? m[1].trim() : null };

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>`;
 }
@@ -251,8 +282,8 @@ 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(activeProjectKey),
+        readMemory(GLOBAL_KEY),
+        readMemory(activeProjectKey),
       ]);
 
       const context = buildMemoryContext(globalFacts, projectFacts, activeProjectKey);
@@ -290,6 +321,10 @@ export const MemoryPlugin = async ({ directory, worktree, client }) => {
           "(name, goals, constraints, tech preferences, project conventions). " +
           "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: {
@@ -307,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);
           }
 
@@ -339,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",
@@ -355,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;
@@ -365,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) => {
@@ -384,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: {
@@ -424,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. " +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotargo/memory_plugin",
-  "version": "1.2.902",
+  "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`)
@@ -121,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]`.