@lotargo/memory_plugin 1.2.902 → 1.3.1

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.1",
   "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,14 +1,15 @@
 ---
 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 & MCP Helper tools (remember, recall, forget, update_fact, memory_info, link_knowledge, ingest_document, query_knowledge_base, manage_knowledge_base, list-mcp-tools, mcp-reminder). Trigger proactively whenever user preferences, project conventions, technology stack choices, or architecture decisions are introduced, or when querying ingested documentation, indexing files/repos, managing persistent knowledge, or looking up available MCP tool integrations.
 ---
 
-# Using Memory & Hybrid RAG Knowledge Engine
+# Using Memory, Hybrid RAG Knowledge Engine & MCP Helper Tools
 
-You have access to a persistent dual-layer memory engine supercharged with an **Agent-Driven Knowledge Graph**:
+You have access to a persistent dual-layer memory engine supercharged with an **Agent-Driven Knowledge Graph** and general MCP integration helpers:
 1. **Layer 1: Notebook Store (Key-Value Facts)**: Stores high-signal personal preferences, project conventions, and durable rules in clean Markdown.
 2. **Layer 2: RAG Knowledge Base**: Indexes documentation, repositories, and technical guides for hybrid semantic retrieval.
 3. **Layer 3: Agent-Driven Knowledge Graph**: Connects Notebook facts (Layer 1) to specific Knowledge Base documents, sections, and **exact line ranges** (Layer 2).
+4. **Integration Layer (General MCP Helpers)**: Quickly discovers connected MCP servers and identifies appropriate tools for specific tasks.
 
 ---
 
@@ -17,17 +18,24 @@ 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` |
 | Read full raw content of an ambiguous/abstract document | `manage_knowledge_base` | `action: "read_document"`, `docId` |
-| User asks to view database stats, list indexed docs, or export snapshots | `manage_knowledge_base` | `action` ("stats", "list", "read_document", "delete", "export_snapshot") |
+| User asks to view database stats, list indexed docs, or export snapshots | `manage_knowledge_base` | `action` ("stats", "list", "read_document", "delete", "export_snapshot", "import_snapshot") |
+| Discover available MCP servers and their specific purposes | `list-mcp-tools` | — |
+| Ask which MCP tool / server is suitable for a specific task | `mcp-reminder` | `task` (string, e.g., "db migration") |
 
 ---
 
-## 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 +58,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`)
@@ -71,7 +116,7 @@ Use this tool when adding technical documentation, API specs, architectural docu
 
 ### Hybrid Retrieval (`query_knowledge_base`)
 Use this tool BEFORE answering deep architectural or technical questions when indexed documents exist.
-- Performs **Hybrid RRF Fusion** combining SQLite FTS5 BM25 keyword matching with dense ONNX vector semantic search.
+- Performs **Hybrid RRF/RSF Fusion** combining SQLite FTS5 BM25 keyword matching with dense ONNX vector semantic search.
 - Returns candidate sections with breadcrumb paths and defined code symbols (classes, functions, types).
 
 #### Query Formulation Rules (CRITICAL for retrieval quality)
@@ -112,13 +157,28 @@ In such cases, use the **Full Raw Document Reading** mechanism:
 - Use `action: "list"` to see all ingested documents.
 - Use `action: "read_document"` with `docId` to read the complete raw text content of any document.
 - Use `action: "delete"` with `docId` to remove an outdated document and purge its CAS blob.
+- Use `action: "export_snapshot"` with `snapshotPath` to export a JSON backup of the RAG base.
+- Use `action: "import_snapshot"` with `snapshotPath` to import and merge a JSON backup into the current database.
+
+---
+
+## 4. General MCP Helpers (`list-mcp-tools`, `mcp-reminder`)
+
+### Discovering Connected MCP Servers (`list-mcp-tools`)
+When working in multi-server environments (e.g., OpenCode, Claude Code), you might have several auxiliary servers installed (for database, UI design, browser automation, etc.).
+- Use `list-mcp-tools` to immediately view all registered servers and their descriptions. This avoids guessing what other capabilities are available in the current workspace.
+
+### Contextual Tool Reminders (`mcp-reminder`)
+- If you are unsure which tool/server is best suited for the task at hand (e.g., how to do browser testing, or run a database migration), run `mcp-reminder(task: "your current task definition")`.
+- It analyzes your task and suggests appropriate servers (like `playwright` for testing, `supabase` for DB, or `stitch` for UI design).
 
 ---
 
-## 4. Core Directives for AI Agents
+## 5. Core Directives for AI Agents
 
 1. **Read Memories First (MANDATORY)**: At the very start of any session or conversation, your VERY FIRST STEP MUST BE to execute `recall` to load all saved facts, user context, and project guidelines BEFORE performing any other task or code analysis.
 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.
+3. **Check Knowledge Base First**: If a query is related to specialized documentation, APIs, or project architectures, 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]`.
+6. **Leverage MCP Servers**: Proactively list available tools using `list-mcp-tools` and query `mcp-reminder` if unsure of which platform tool can help you automate tasks.