@xultrax-web/agent-memory-mcp 0.6.0 → 0.8.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 xultrax-web
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 xultrax-web
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -185,18 +185,32 @@ Custom path:
 
 ## Tools
 
-| Tool                | Purpose                                                                                                                                        |
-| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| `save_memory`       | Create or update a memory. Atomic write + locked. Validates name + type. Updates the index.                                                    |
-| `search_memories`   | Fuzzy search (Fuse.js · typo-tolerant, word-order tolerant, partial matches). Returns top N with relevance 0-100 + body snippet.               |
-| `relevant_memories` | Same matching as search, but returns full memory bodies as one markdown doc. Built for LLM auto-context.                                       |
-| `get_memory`        | Fetch one memory by name. Returns frontmatter + body.                                                                                          |
-| `list_memories`     | List memories. Optional `type` filter. Paginated (default 50/page).                                                                            |
-| `delete_memory`     | Soft delete: moves the memory to `.trash/<ts>-<name>.md`. Recoverable until you empty `.trash/` by hand.                                       |
-| `restore_memory`    | Restore a soft-deleted memory from `.trash/`. Picks the most recent trash entry for the name.                                                  |
-| `doctor`            | Storage integrity check. Reports orphans, dangling index entries, unreadable files. Pass `rebuild-index=true` to repair `MEMORY.md` from disk. |
-| `stats`             | Dashboard: counts per type, total size, largest memory, audit-log size, trash count.                                                           |
-| `log_events`        | Read recent entries from the audit event log. Optional `tail` (default 20) + `action` filter.                                                  |
+| Tool                | Purpose                                                                                                                                                                     |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `save_memory`       | Create or update a memory. Atomic write + locked. Validates name + type. Updates the index.                                                                                 |
+| `search_memories`   | Fuzzy search (Fuse.js · typo-tolerant, word-order tolerant, partial matches). Returns top N with relevance 0-100 + body snippet.                                            |
+| `relevant_memories` | Same matching as search, but returns full memory bodies as one markdown doc. Built for LLM auto-context.                                                                    |
+| `get_memory`        | Fetch one memory by name. Returns frontmatter + body.                                                                                                                       |
+| `list_memories`     | List memories. Optional `type` filter. Paginated (default 50/page).                                                                                                         |
+| `delete_memory`     | Soft delete: moves the memory to `.trash/<ts>-<name>.md`. Recoverable until you empty `.trash/` by hand.                                                                    |
+| `restore_memory`    | Restore a soft-deleted memory from `.trash/`. Picks the most recent trash entry for the name.                                                                               |
+| `doctor`            | Storage integrity check. Reports orphans, dangling index entries, unreadable files. Pass `rebuild-index=true` to repair `MEMORY.md` from disk.                              |
+| `stats`             | Dashboard: counts per type, total size, largest memory, audit-log size, trash count.                                                                                        |
+| `log_events`        | Read recent entries from the audit event log. Optional `tail` (default 20) + `action` filter.                                                                               |
+| `verify_memory`     | Re-evaluate a memory's claims. Extracts URLs/dates/file refs, flags stale-date signals, returns type-specific verification heuristics. Pairs with the `audit_stale` prompt. |
+| `find_backlinks`    | List memories that link to the given memory via `[[wiki-link]]` syntax in their bodies. Useful for "what references this" views.                                            |
+| `find_related`      | Surface memories related to one by combining outbound links, inbound backlinks, shared tags, type match, and content similarity. Navigates the memory graph by association. |
+
+### Prompts
+
+The server exposes 4 built-in MCP prompts that clients (Claude Desktop, Cursor, etc.) surface as slash-commands. These turn memory into an active workflow layer, not just a passive store:
+
+| Prompt             | Arguments            | What it does                                                                                                                            |
+| ------------------ | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `extract_memories` | none                 | LLM scans the current conversation, proposes candidate memories, and calls `save_memory` for each one (with type + description chosen). |
+| `summarize_topic`  | `topic`              | LLM pulls memories relevant to the topic via `relevant_memories` and synthesizes them into a single summary with citations.             |
+| `prepare_handoff`  | `project` (optional) | LLM walks project-type memories matching the filter and assembles a structured handoff doc (current state, open items, watch-outs).     |
+| `audit_stale`      | none                 | LLM evaluates project + reference memories for staleness and produces a triage list (likely stale / worth verifying / still fresh).     |
 
 ### Memory types
 
@@ -207,6 +221,23 @@ Four built-in types, matching the Claude Code convention:
 - **project** — current-state context that isn't in the code (deadlines, in-flight work)
 - **reference** — pointers to external systems (Linear board URL, monitoring dashboard)
 
+### Tags + wiki-links
+
+Beyond types, two cross-cutting organization features:
+
+**Tags** — optional `tags: [a, b, c]` array in frontmatter. Queryable via `list_memories({tags: [...]})` and the `agent-memory list --tags "a,b"` CLI. Filter is intersection — memories must have all listed tags. Tag names are lowercase a-z + digits + hyphen/underscore, max 40 chars.
+
+```markdown
+---
+name: deploy-process
+description: Blue-green prod deployment
+type: project
+tags: [deployment, production, critical]
+---
+```
+
+**Wiki-links** — write `[[memory-name]]` anywhere in a memory body and it becomes a link. `find_backlinks` returns memories that reference a given one; `find_related` ranks the full graph (outbound links, inbound backlinks, shared tags, content similarity) for discovery navigation.
+
 ---
 
 ## CLI
@@ -229,6 +260,11 @@ agent-memory doctor --rebuild-index            # repair MEMORY.md from disk
 agent-memory stats                             # dashboard: counts, sizes, audit/trash
 agent-memory log                               # last 20 entries from the audit log
 agent-memory log --tail 50 --action delete     # filter by action, tail size
+agent-memory verify deploy-process             # extract URLs/dates/file refs + staleness heuristics
+agent-memory save my-mem --type project --description "X" --content "Body" --tags "production,critical"
+agent-memory list --tags "production"          # filter by tag (intersection)
+agent-memory backlinks deploy-process          # memories that link to deploy-process
+agent-memory related deploy-process            # ranked discovery: links + tags + similarity
 ```
 
 ### Audit log + structured logging
@@ -326,15 +362,29 @@ This server is built to be used daily, not to demo well once.
 
 **Shipped in v0.6:**
 
-- **Vitest test suite** — 20+ blackbox tests covering CLI + MCP server paths.
-- **GitHub Actions CI** — runs tests on every push/PR across Node 18/20/22.
+- **Vitest test suite** — 25+ blackbox tests covering CLI + MCP server paths.
+- **GitHub Actions CI** — runs tests on every push/PR across Node 20/22/24.
 - **[COMPATIBILITY.md](COMPATIBILITY.md)** — known-working client matrix + quirks.
 
-**Landing in v0.7:**
+**Shipped in v0.7 · the active context layer:**
+
+- **MCP Prompts capability** — 4 built-in workflows (`extract_memories`, `summarize_topic`, `prepare_handoff`, `audit_stale`) that the client surfaces as slash-commands.
+- **`verify_memory` tool** — static analysis of a memory's URLs/dates/file refs with type-specific staleness heuristics. Plus the matching `agent-memory verify <name>` CLI.
+- **Conflict detection on save** — fuzzy-matches new memories against existing ones; warns on near-duplicates without blocking the save (so the LLM can decide whether to merge, rename, or proceed).
+
+**Shipped in v0.8 · organization at scale:**
+
+- **Tags** — optional `tags: [...]` array in frontmatter. Queryable via `list_memories` and `agent-memory list --tags "a,b"`. Intersection filter.
+- **`[[wiki-links]]`** — write `[[memory-name]]` in any memory body, auto-detected.
+- **`find_backlinks`** tool + `agent-memory backlinks <name>` CLI — "what links to this".
+- **`find_related`** tool + `agent-memory related <name>` CLI — combines outbound + inbound links, shared tags, type match, and content similarity into a ranked discovery view.
+
+**Landing in v0.9+:**
 
-- Read-only mode (`AGENT_MEMORY_READ_ONLY=1`)
-- Live multi-client verification (Cursor, Cline, Claude Desktop, Continue)
-- Demo GIF / screencast
+- Folder support (`.agent-memory/work/`, `.agent-memory/personal/`)
+- TUI / web UI for browsing + editing memories in a clean interface
+- `agent-memory sync` for git-backed multi-machine memory (the moat)
+- Memory packs for shareable curated bundles
 
 ---
 

package/dist/index.js

@@ -23,7 +23,7 @@
  */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import Fuse from "fuse.js";
 import matter from "gray-matter";
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync, } from "node:fs";
@@ -171,6 +171,12 @@ const VALID_TYPES = new Set(["user", "feedback", "project", "reference"]);
 // a letter or digit, 1-80 chars. Underscores are allowed because Claude
 // Code's memory tree uses them; we want frictionless import.
 const SLUG_PATTERN = /^[a-z0-9][a-z0-9_-]{0,80}$/;
+// Tags: lowercase, digits, hyphen/underscore. Max 40 chars per tag.
+// Same alphabet as slugs but shorter — meant for "container-industry",
+// "weekly", "deprecated", etc.
+const TAG_PATTERN = /^[a-z0-9][a-z0-9_-]{0,40}$/;
+// Wiki-links: [[memory-name]] · names follow SLUG_PATTERN rules
+const WIKI_LINK_PATTERN = /\[\[([a-z0-9][a-z0-9_-]{0,80})\]\]/g;
 function memoryFilePath(name) {
     return join(MEMORY_DIR, `${name}.md`);
 }
@@ -185,6 +191,7 @@ function readMemory(name) {
         name: fm.name ?? name,
         description: fm.description ?? "",
         type: fm.type ?? "project",
+        tags: Array.isArray(fm.tags) ? fm.tags.filter((t) => typeof t === "string") : [],
         body: parsed.content.trim(),
         filePath: fp,
     };
@@ -196,6 +203,50 @@ function listMemoryFiles() {
         .filter((f) => f.endsWith(".md") && f !== "MEMORY.md")
         .map((f) => f.replace(/\.md$/, ""));
 }
+// Tags can arrive as a string array (MCP/CLI args) or a comma-separated
+// string (CLI flag). Normalize to a deduped lowercase string[] preserving
+// order of first appearance.
+function normalizeTags(input) {
+    if (!input)
+        return [];
+    let raw;
+    if (Array.isArray(input)) {
+        raw = input.map((t) => String(t).trim()).filter((t) => t.length > 0);
+    }
+    else if (typeof input === "string") {
+        raw = input
+            .split(",")
+            .map((t) => t.trim())
+            .filter((t) => t.length > 0);
+    }
+    else {
+        return [];
+    }
+    const seen = new Set();
+    const out = [];
+    for (const t of raw) {
+        const lower = t.toLowerCase();
+        if (!seen.has(lower)) {
+            seen.add(lower);
+            out.push(lower);
+        }
+    }
+    return out;
+}
+// Extract [[wiki-link]] targets from a memory body. Returns the set of
+// referenced memory names (deduped, lowercase). Self-references stripped.
+function extractWikiLinks(body, selfName) {
+    const found = new Set();
+    let m;
+    // RegExp with /g flag needs reset of lastIndex per call
+    WIKI_LINK_PATTERN.lastIndex = 0;
+    while ((m = WIKI_LINK_PATTERN.exec(body)) !== null) {
+        const target = m[1].toLowerCase();
+        if (target !== selfName)
+            found.add(target);
+    }
+    return Array.from(found);
+}
 // -------------------------------------------------------------
 // Index management
 // -------------------------------------------------------------
@@ -236,48 +287,137 @@ function toolSaveMemory(args) {
     const description = String(args.description ?? "").trim();
     const type = String(args.type ?? "project").trim();
     const content = String(args.content ?? "").trim();
+    const tags = normalizeTags(args.tags);
     if (!SLUG_PATTERN.test(name)) {
         throw new Error(`Invalid name "${name}". Use lowercase (a-z, 0-9, hyphen, underscore), 1-80 chars, must start with letter or digit.`);
     }
     if (!VALID_TYPES.has(type)) {
         throw new Error(`Invalid type "${type}". Must be one of: ${Array.from(VALID_TYPES).join(", ")}.`);
     }
+    for (const tag of tags) {
+        if (!TAG_PATTERN.test(tag)) {
+            throw new Error(`Invalid tag "${tag}". Tags use lowercase (a-z, 0-9, hyphen, underscore), 1-40 chars.`);
+        }
+    }
     if (!description)
         throw new Error("description is required");
     if (!content)
         throw new Error("content is required");
     ensureStorage();
+    const tagsLine = tags.length > 0 ? `tags: [${tags.map((t) => JSON.stringify(t)).join(", ")}]\n` : "";
     const frontmatter = `---\n` +
         `name: ${name}\n` +
         `description: ${JSON.stringify(description)}\n` +
         `type: ${type}\n` +
+        tagsLine +
         `schema: ${SCHEMA_VERSION}\n` +
         `---\n\n`;
     const fp = memoryFilePath(name);
     const isUpdate = existsSync(fp);
+    // Conflict detection · only when creating a NEW memory (updates are
+    // intentional re-saves and don't need a similarity warning). Fuzzy
+    // match against existing names + descriptions; if anything scores
+    // above the conflict threshold, warn but don't block — the LLM can
+    // decide whether to merge, rename, or proceed.
+    let conflictWarning = "";
+    if (!isUpdate) {
+        const conflicts = detectConflicts({ name, description, type });
+        if (conflicts.length > 0) {
+            const list = conflicts
+                .map((c) => `  - ${c.name} [${c.type}] (${c.similarity}% similar)`)
+                .join("\n");
+            conflictWarning =
+                `\n\nWARNING · potentially similar existing memory(ies):\n${list}\n` +
+                    `Consider merging or renaming. To proceed anyway, the save has already been completed.`;
+        }
+    }
     return withLock(() => {
         atomicWriteFile(fp, frontmatter + content + "\n");
         upsertIndexEntryUnlocked(name, description);
-        logEvent("save", { name, type, update: isUpdate, bytes: content.length });
+        logEvent("save", {
+            name,
+            type,
+            update: isUpdate,
+            bytes: content.length,
+            conflicts: conflictWarning ? "warned" : undefined,
+        });
         log("debug", "save_memory", { name, type, update: isUpdate });
-        return `${isUpdate ? "Updated" : "Saved"} memory "${name}" (${type}) at ${fp}`;
+        return `${isUpdate ? "Updated" : "Saved"} memory "${name}" (${type}) at ${fp}${conflictWarning}`;
+    });
+}
+function detectConflicts(candidate) {
+    const names = listMemoryFiles();
+    // Skip the candidate name itself (will be an update, not a conflict)
+    const others = names.filter((n) => n !== candidate.name);
+    if (others.length === 0)
+        return [];
+    const existing = others.map((n) => readMemory(n)).filter((m) => m !== null);
+    if (existing.length === 0)
+        return [];
+    // Two separate searches catch different conflict shapes:
+    //   - Name-based: matches when the new slug is very close to an
+    //     existing slug (e.g. "deploy-process" vs "deployment-strategy")
+    //   - Description-based: matches when descriptions are paraphrases
+    //     of each other regardless of name
+    // We merge results + dedupe. Threshold 0.5 here is intentionally
+    // looser than search (0.4) because we'd rather warn on a few false
+    // positives than miss an obvious duplicate.
+    // Threshold 0.6 catches paraphrases like "deployment-strategy" vs
+    // "deploy-process" (Fuse Bitap scores those around 0.5). The 45%
+    // similarity floor below then trims out the long tail.
+    const nameFuse = new Fuse(existing, {
+        includeScore: true,
+        threshold: 0.6,
+        ignoreLocation: true,
+        minMatchCharLength: 3,
+        keys: ["name"],
+    });
+    const descFuse = new Fuse(existing, {
+        includeScore: true,
+        threshold: 0.6,
+        ignoreLocation: true,
+        minMatchCharLength: 3,
+        keys: ["description"],
     });
+    const merged = new Map();
+    const addHit = (name, type, score) => {
+        const existingHit = merged.get(name);
+        const similarity = Math.round((1 - score) * 100);
+        if (!existingHit || similarity > existingHit.similarity) {
+            merged.set(name, { name, type, similarity });
+        }
+    };
+    for (const r of nameFuse.search(candidate.name, { limit: 3 })) {
+        addHit(r.item.name, r.item.type, r.score ?? 1);
+    }
+    for (const r of descFuse.search(candidate.description, { limit: 3 })) {
+        addHit(r.item.name, r.item.type, r.score ?? 1);
+    }
+    return Array.from(merged.values())
+        .filter((h) => h.similarity >= 45) // 45%+ similarity = worth surfacing
+        .sort((a, b) => b.similarity - a.similarity)
+        .slice(0, 3);
 }
 function toolGetMemory(args) {
     const name = String(args.name ?? "").trim();
     const mem = readMemory(name);
     if (!mem)
         return `Memory "${name}" not found.`;
+    const tagsLine = mem.tags.length > 0 ? `tags        : ${mem.tags.join(", ")}` : "";
     return [
         `# ${mem.name}`,
-        `type: ${mem.type}`,
-        `description: ${mem.description}`,
+        `type        : ${mem.type}`,
+        tagsLine,
+        `description : ${mem.description}`,
         "",
         mem.body,
-    ].join("\n");
+    ]
+        .filter((l) => l !== "")
+        .join("\n");
 }
 function toolListMemories(args) {
     const typeFilter = args.type ? String(args.type) : null;
+    const tagFilter = normalizeTags(args.tags);
     const offset = args.offset ? Math.max(0, Number(args.offset)) : 0;
     const limit = args.limit ? Math.max(1, Number(args.limit)) : 50;
     const names = listMemoryFiles();
@@ -285,21 +425,34 @@ function toolListMemories(args) {
         .map((n) => readMemory(n))
         .filter((m) => m !== null)
         .filter((m) => !typeFilter || m.type === typeFilter)
+        .filter((m) => tagFilter.length === 0 || tagFilter.every((t) => m.tags.includes(t)))
         .sort((a, b) => a.name.localeCompare(b.name));
     if (all.length === 0) {
-        return typeFilter
-            ? `No memories of type "${typeFilter}".`
+        const parts = [];
+        if (typeFilter)
+            parts.push(`type "${typeFilter}"`);
+        if (tagFilter.length > 0)
+            parts.push(`tags [${tagFilter.join(", ")}]`);
+        return parts.length > 0
+            ? `No memories matching ${parts.join(" and ")}.`
             : "No memories yet. Use save_memory to create one.";
     }
     const page = all.slice(offset, offset + limit);
     const lines = [];
+    const filterDesc = [
+        typeFilter ? `type=${typeFilter}` : null,
+        tagFilter.length > 0 ? `tags=[${tagFilter.join(",")}]` : null,
+    ]
+        .filter(Boolean)
+        .join(" ");
     const showing = offset === 0 && page.length === all.length
-        ? `Found ${all.length} memor${all.length === 1 ? "y" : "ies"}:`
-        : `Showing ${offset + 1}-${offset + page.length} of ${all.length}:`;
+        ? `Found ${all.length} memor${all.length === 1 ? "y" : "ies"}${filterDesc ? ` (${filterDesc})` : ""}:`
+        : `Showing ${offset + 1}-${offset + page.length} of ${all.length}${filterDesc ? ` (${filterDesc})` : ""}:`;
     lines.push(showing);
     lines.push("");
     for (const m of page) {
-        lines.push(`  ${m.name}  [${m.type}]`);
+        const tagSuffix = m.tags.length > 0 ? `  ${c(ANSI.dim, `· ${m.tags.join(" · ")}`)}` : "";
+        lines.push(`  ${m.name}  [${m.type}]${tagSuffix}`);
         lines.push(`    ${m.description}`);
     }
     if (offset + page.length < all.length) {
@@ -558,6 +711,208 @@ function toolDoctor(args) {
     return formatDoctorReport(report, rebuild);
 }
 // -------------------------------------------------------------
+// verify_memory · re-evaluate a memory's claims
+// -------------------------------------------------------------
+//
+// Static analysis only (no network calls — MCP servers may run
+// offline). Extracts URLs + dates + file paths from the body and
+// returns a structured report the LLM can act on. Pairs with the
+// audit_stale prompt to triage memory hygiene.
+const URL_PATTERN = /\bhttps?:\/\/[^\s<>"')]+/g;
+const DATE_PATTERN = /\b(20\d{2})-(\d{2})-(\d{2})\b/g;
+const FILE_PATH_PATTERN = /\b(?:[A-Za-z]:\\|\/)?(?:[\w.-]+[\\/])+[\w.-]+\.\w+\b/g;
+function toolVerifyMemory(args) {
+    const name = String(args.name ?? "").trim();
+    if (!SLUG_PATTERN.test(name))
+        throw new Error(`Invalid name "${name}".`);
+    const mem = readMemory(name);
+    if (!mem)
+        return `Memory "${name}" not found.`;
+    const urls = Array.from(new Set(mem.body.match(URL_PATTERN) ?? []));
+    const dates = Array.from(new Set((mem.body.match(DATE_PATTERN) ?? []).map((d) => d)));
+    const filePaths = Array.from(new Set(mem.body.match(FILE_PATH_PATTERN) ?? []));
+    // Staleness heuristic: if any date in the body is more than 60 days
+    // old AND the memory type is project, flag it for review.
+    const now = Date.now();
+    const SIXTY_DAYS = 60 * 24 * 3600 * 1000;
+    const oldDates = dates.filter((d) => {
+        const parsed = Date.parse(d);
+        return !isNaN(parsed) && now - parsed > SIXTY_DAYS;
+    });
+    const lines = [];
+    lines.push(c(ANSI.bold, `verify_memory · ${mem.name}`));
+    lines.push(`type        : ${mem.type}`);
+    lines.push(`description : ${mem.description}`);
+    lines.push("");
+    lines.push(c(ANSI.bold, "Static signals:"));
+    lines.push(`  URLs found        : ${urls.length}`);
+    lines.push(`  Dates referenced  : ${dates.length}${oldDates.length > 0 ? ` (${oldDates.length} > 60 days old)` : ""}`);
+    lines.push(`  File-path refs    : ${filePaths.length}`);
+    if (urls.length > 0) {
+        lines.push("");
+        lines.push(c(ANSI.bold, "URLs to verify:"));
+        for (const u of urls.slice(0, 10))
+            lines.push(`  - ${u}`);
+        if (urls.length > 10)
+            lines.push(`  ... +${urls.length - 10} more`);
+    }
+    if (oldDates.length > 0) {
+        lines.push("");
+        lines.push(c(ANSI.yellow, "Stale-date signals (consider whether claims are still current):"));
+        for (const d of oldDates.slice(0, 5))
+            lines.push(`  - ${d}`);
+    }
+    if (filePaths.length > 0 && filePaths.length <= 10) {
+        lines.push("");
+        lines.push(c(ANSI.bold, "File paths referenced:"));
+        for (const fp of filePaths)
+            lines.push(`  - ${fp}`);
+    }
+    lines.push("");
+    lines.push(c(ANSI.bold, "Type-specific verification heuristics:"));
+    switch (mem.type) {
+        case "reference":
+            lines.push("  - HEAD-check each URL above (200 = alive, 404 = dead, 410 = gone)");
+            lines.push("  - Verify the resource still says what the memory claims it says");
+            break;
+        case "project":
+            lines.push("  - Check if any dates above are stale relative to current project state");
+            lines.push("  - Cross-reference any names/people mentioned against current org chart");
+            lines.push("  - Verify any deadlines or commitments haven't already passed");
+            break;
+        case "feedback":
+            lines.push("  - Confirm the rule still applies (operator hasn't changed their mind)");
+            lines.push("  - Check the **Why:** is still load-bearing — if the original reason is gone, the rule may be obsolete");
+            break;
+        case "user":
+            lines.push("  - User preferences drift over time; ask the operator if a 6+ month old memory still holds");
+            break;
+    }
+    lines.push("");
+    lines.push(c(ANSI.dim, "Memory body for review:"));
+    lines.push("");
+    lines.push(mem.body);
+    return lines.join("\n");
+}
+// -------------------------------------------------------------
+// Backlinks · which memories link to this one via [[wiki-link]]
+// -------------------------------------------------------------
+function toolFindBacklinks(args) {
+    const name = String(args.name ?? "").trim();
+    if (!SLUG_PATTERN.test(name))
+        throw new Error(`Invalid name "${name}".`);
+    const target = name.toLowerCase();
+    const all = listMemoryFiles()
+        .map((n) => readMemory(n))
+        .filter((m) => m !== null);
+    const backlinks = [];
+    for (const m of all) {
+        if (m.name === name)
+            continue;
+        const links = extractWikiLinks(m.body, m.name);
+        if (links.includes(target))
+            backlinks.push(m);
+    }
+    if (backlinks.length === 0)
+        return `No memories link to [[${name}]].`;
+    const lines = [];
+    lines.push(c(ANSI.bold, `Found ${backlinks.length} memor${backlinks.length === 1 ? "y" : "ies"} linking to [[${name}]]:`));
+    lines.push("");
+    for (const m of backlinks.sort((a, b) => a.name.localeCompare(b.name))) {
+        lines.push(`  ${m.name}  [${m.type}]`);
+        lines.push(`    ${m.description}`);
+    }
+    return lines.join("\n");
+}
+function toolFindRelated(args) {
+    const name = String(args.name ?? "").trim();
+    if (!SLUG_PATTERN.test(name))
+        throw new Error(`Invalid name "${name}".`);
+    const mem = readMemory(name);
+    if (!mem)
+        return `Memory "${name}" not found.`;
+    const max = args.max ? Math.max(1, Math.min(20, Number(args.max))) : 8;
+    const others = listMemoryFiles()
+        .filter((n) => n !== name)
+        .map((n) => readMemory(n))
+        .filter((m) => m !== null);
+    if (others.length === 0)
+        return `No other memories to compare against.`;
+    const outbound = new Set(extractWikiLinks(mem.body, mem.name));
+    const myTags = new Set(mem.tags);
+    // Fuzzy similarity against name + description only (body content is
+    // too noisy for relatedness; we already cover semantic overlap via
+    // search_memories).
+    const fuse = new Fuse(others, {
+        includeScore: true,
+        threshold: 0.7,
+        ignoreLocation: true,
+        minMatchCharLength: 3,
+        keys: [
+            { name: "name", weight: 2 },
+            { name: "description", weight: 1 },
+        ],
+    });
+    const fuzzy = new Map();
+    const query = `${mem.name} ${mem.description}`;
+    for (const r of fuse.search(query, { limit: 20 })) {
+        fuzzy.set(r.item.name, 1 - (r.score ?? 1));
+    }
+    const scored = new Map();
+    for (const other of others) {
+        let score = 0;
+        const reasons = [];
+        if (outbound.has(other.name)) {
+            score += 5;
+            reasons.push("linked from this memory");
+        }
+        const otherOutbound = extractWikiLinks(other.body, other.name);
+        if (otherOutbound.includes(mem.name)) {
+            score += 5;
+            reasons.push("links to this memory");
+        }
+        const sharedTags = other.tags.filter((t) => myTags.has(t));
+        if (sharedTags.length > 0) {
+            score += sharedTags.length * 3;
+            reasons.push(`shared tags: ${sharedTags.join(", ")}`);
+        }
+        if (other.type === mem.type) {
+            score += 1;
+        }
+        const sim = fuzzy.get(other.name);
+        if (sim && sim > 0.3) {
+            score += Math.round(sim * 4);
+            reasons.push(`content similarity ${Math.round(sim * 100)}%`);
+        }
+        if (score > 0) {
+            scored.set(other.name, {
+                name: other.name,
+                type: other.type,
+                tags: other.tags,
+                description: other.description,
+                score,
+                reasons,
+            });
+        }
+    }
+    const ranked = Array.from(scored.values())
+        .sort((a, b) => b.score - a.score)
+        .slice(0, max);
+    if (ranked.length === 0)
+        return `No memories related to "${name}" found.`;
+    const lines = [];
+    lines.push(c(ANSI.bold, `Memories related to ${name}:`));
+    lines.push("");
+    for (const r of ranked) {
+        lines.push(`  ${r.name}  [${r.type}]  ${c(ANSI.dim, `· score ${r.score}`)}`);
+        lines.push(`    ${r.description}`);
+        for (const reason of r.reasons) {
+            lines.push(`    ${c(ANSI.dim, `· ${reason}`)}`);
+        }
+    }
+    return lines.join("\n");
+}
+// -------------------------------------------------------------
 // Stats · operator dashboard
 // -------------------------------------------------------------
 function toolStats(_args) {
@@ -667,7 +1022,7 @@ function actionColor(action) {
 // -------------------------------------------------------------
 // Server wiring
 // -------------------------------------------------------------
-const server = new Server({ name: "agent-memory", version: "0.2.0" }, { capabilities: { tools: {}, resources: {} } });
+const server = new Server({ name: "agent-memory", version: "0.8.0" }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
 // -------------------------------------------------------------
 // Resource URI scheme
 // -------------------------------------------------------------
@@ -727,6 +1082,169 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
     }
     throw new Error(`Unknown resource URI: ${uri}. Supported: ${URI_INDEX}, ${URI_MEMORY_PREFIX}{name}`);
 });
+const PROMPTS = [
+    {
+        name: "extract_memories",
+        description: "Scan the current conversation for things worth remembering. Returns a structured prompt asking the LLM to identify candidate memories and call save_memory for each one.",
+    },
+    {
+        name: "summarize_topic",
+        description: "Pull memories relevant to a topic and ask the LLM to synthesize them into a single coherent summary.",
+        arguments: [
+            { name: "topic", description: "What to summarize what's known about.", required: true },
+        ],
+    },
+    {
+        name: "prepare_handoff",
+        description: "Generate a project state snapshot from all project-type memories matching a filter. Useful for rotating on-call, end-of-day handoffs, or onboarding a collaborator.",
+        arguments: [
+            {
+                name: "project",
+                description: "Substring to filter project memories by (matches name + description + tags).",
+                required: false,
+            },
+        ],
+    },
+    {
+        name: "audit_stale",
+        description: "Walk recent project and reference memories and ask the LLM to flag which ones are likely stale or contradicted by current state. Pairs with verify_memory for follow-up.",
+    },
+];
+server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+    prompts: PROMPTS,
+}));
+server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+    const { name, arguments: args = {} } = request.params;
+    ensureStorage();
+    switch (name) {
+        case "extract_memories":
+            return {
+                description: PROMPTS[0].description,
+                messages: [
+                    {
+                        role: "user",
+                        content: {
+                            type: "text",
+                            text: [
+                                "Scan the current conversation for facts, rules, preferences, decisions, or context that would be useful to remember across future sessions. Focus on things that:",
+                                "",
+                                "- Reflect the operator's stable preferences or working style (type=user)",
+                                "- Represent rules the assistant should follow going forward (type=feedback)",
+                                "- Capture current-state context not derivable from code or docs (type=project)",
+                                "- Point at external resources the operator references (type=reference)",
+                                "",
+                                "For each candidate, call the save_memory tool with:",
+                                "  - name: a short kebab-case slug (a-z, 0-9, -, _)",
+                                "  - type: one of user | feedback | project | reference",
+                                "  - description: a one-line summary used in the index",
+                                "  - content: the memory body in markdown. For feedback/project, include `**Why:**` and `**How to apply:**` lines.",
+                                "",
+                                "Before saving each one, briefly explain why it's worth remembering. Skip anything that's already obvious from code or that's only relevant to the current session.",
+                                "",
+                                "If there's nothing worth saving, say so plainly and stop.",
+                            ].join("\n"),
+                        },
+                    },
+                ],
+            };
+        case "summarize_topic": {
+            const topic = String(args.topic ?? "").trim();
+            if (!topic)
+                throw new Error("summarize_topic requires a 'topic' argument");
+            return {
+                description: PROMPTS[1].description,
+                messages: [
+                    {
+                        role: "user",
+                        content: {
+                            type: "text",
+                            text: [
+                                `Call the relevant_memories tool with query="${topic}" (max=10).`,
+                                "",
+                                "Then synthesize the returned memories into a single coherent summary covering:",
+                                "",
+                                "1. What's established / known",
+                                "2. Open questions or unresolved tensions across the memories",
+                                "3. Any stale or contradicted claims worth flagging",
+                                "",
+                                "Keep it tight — aim for one paragraph per section unless the material is genuinely dense. Cite the source memory names inline as `[memory-name]`.",
+                            ].join("\n"),
+                        },
+                    },
+                ],
+            };
+        }
+        case "prepare_handoff": {
+            const project = String(args.project ?? "").trim();
+            const filterClause = project
+                ? `filtered to project memories matching "${project}"`
+                : "across all project memories";
+            return {
+                description: PROMPTS[2].description,
+                messages: [
+                    {
+                        role: "user",
+                        content: {
+                            type: "text",
+                            text: [
+                                `Generate a project handoff document ${filterClause}.`,
+                                "",
+                                project
+                                    ? `Start by calling list_memories with type="project", then filter the results by substring match against "${project}".`
+                                    : `Start by calling list_memories with type="project" to get the full set.`,
+                                "",
+                                "For each relevant memory, call get_memory to load its full body. Then produce a single handoff document with these sections:",
+                                "",
+                                "## Current state",
+                                "What's in flight or recently shipped, distilled from project memories.",
+                                "",
+                                "## Open items",
+                                "Anything explicitly noted as pending, waiting, or unresolved.",
+                                "",
+                                "## Watch-outs",
+                                "Constraints, deadlines, or hidden gotchas captured in memory.",
+                                "",
+                                "## Reference material",
+                                "Links and external resources the next person should know about (from reference memories if they're relevant to the project).",
+                                "",
+                                "Cite source memories inline as `[memory-name]`. Keep prose dense; this is meant to be read by an experienced operator, not explained from scratch.",
+                            ].join("\n"),
+                        },
+                    },
+                ],
+            };
+        }
+        case "audit_stale":
+            return {
+                description: PROMPTS[3].description,
+                messages: [
+                    {
+                        role: "user",
+                        content: {
+                            type: "text",
+                            text: [
+                                'Call list_memories with type="project", then list_memories with type="reference". For each memory returned, evaluate whether its claims are likely still true based on:',
+                                "",
+                                "- Dates in the body (anything more than 30 days old in a `project` memory deserves scrutiny)",
+                                "- References to people, dependencies, or systems that may have changed",
+                                "- Claims about external state (URLs, dashboards, APIs) that you can't verify without external access",
+                                "",
+                                "Produce a triage list with three buckets:",
+                                "",
+                                "**Likely stale** (high confidence they're outdated) — explain why, suggest action.",
+                                "**Worth verifying** (claims you can't evaluate without external access) — suggest using the verify_memory tool.",
+                                "**Still fresh** (nothing in the content suggests staleness).",
+                                "",
+                                "Be conservative on the 'likely stale' bucket — false positives there create work for the operator.",
+                            ].join("\n"),
+                        },
+                    },
+                ],
+            };
+        default:
+            throw new Error(`Unknown prompt: ${name}`);
+    }
+});
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
         {
@@ -754,6 +1272,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                         type: "string",
                         description: "Markdown body. For feedback/project, include **Why:** and **How to apply:** lines.",
                     },
+                    tags: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Optional tags for cross-cutting categorization. Lowercase, kebab/underscore, max 40 chars each. Queryable in list_memories + search_memories.",
+                    },
                 },
                 required: ["name", "description", "type", "content"],
             },
@@ -801,7 +1324,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             name: "list_memories",
-            description: "List stored memories, optionally filtered by type. Paginated.",
+            description: "List stored memories, optionally filtered by type and/or tags. Paginated.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -810,6 +1333,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                         enum: ["user", "feedback", "project", "reference"],
                         description: "Optional filter — only list memories of this type",
                     },
+                    tags: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Optional tag filter — memories must have ALL listed tags (intersection). Can also be passed as a comma-separated string.",
+                    },
                     offset: { type: "number", description: "Skip this many results (default 0)." },
                     limit: { type: "number", description: "Max results per page (default 50)." },
                 },
@@ -869,6 +1397,43 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 },
             },
         },
+        {
+            name: "verify_memory",
+            description: "Re-evaluate a memory's claims against signals in its content. Extracts URLs, dates, and file paths from the body; flags stale-date signals on project-type memories; returns type-specific verification heuristics for the LLM or operator to act on. Pairs with the audit_stale prompt.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    name: { type: "string", description: "The memory's name slug" },
+                },
+                required: ["name"],
+            },
+        },
+        {
+            name: "find_backlinks",
+            description: "List memories that link to the given memory via [[wiki-link]] syntax in their bodies. Useful for building a 'what references this' view.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    name: { type: "string", description: "The memory's name slug" },
+                },
+                required: ["name"],
+            },
+        },
+        {
+            name: "find_related",
+            description: "Surface memories related to a given one. Ranks by combining: outbound [[wiki-links]], inbound backlinks, shared tags, same type, and content similarity (name + description). Use this to navigate the memory graph by association rather than by exact lookup.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    name: { type: "string", description: "The starting memory's name slug" },
+                    max: {
+                        type: "number",
+                        description: "Max related memories to return (default 8, capped at 20).",
+                    },
+                },
+                required: ["name"],
+            },
+        },
     ],
 }));
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -906,6 +1471,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case "log_events":
                 result = toolLogEvents(args);
                 break;
+            case "verify_memory":
+                result = toolVerifyMemory(args);
+                break;
+            case "find_backlinks":
+                result = toolFindBacklinks(args);
+                break;
+            case "find_related":
+                result = toolFindRelated(args);
+                break;
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }
@@ -938,6 +1512,9 @@ const CLI_COMMANDS = new Set([
     "doctor",
     "stats",
     "log",
+    "verify",
+    "backlinks",
+    "related",
     "import-claude-code",
     "help",
     "--help",
@@ -1006,6 +1583,7 @@ async function cliMain(command, rest) {
                     type: String(flags.type ?? "project"),
                     description: String(flags.description ?? ""),
                     content,
+                    tags: flags.tags,
                 });
                 process.stdout.write(result + "\n");
                 return 0;
@@ -1040,6 +1618,7 @@ async function cliMain(command, rest) {
             case "list": {
                 process.stdout.write(toolListMemories({
                     type: flags.type,
+                    tags: flags.tags,
                     offset: flags.offset ? Number(flags.offset) : undefined,
                     limit: flags.limit ? Number(flags.limit) : undefined,
                 }) + "\n");
@@ -1067,6 +1646,30 @@ async function cliMain(command, rest) {
                 process.stdout.write(toolStats({}) + "\n");
                 return 0;
             }
+            case "verify": {
+                const name = positional[0];
+                if (!name)
+                    throw new Error("Usage: agent-memory verify <name>");
+                process.stdout.write(toolVerifyMemory({ name }) + "\n");
+                return 0;
+            }
+            case "backlinks": {
+                const name = positional[0];
+                if (!name)
+                    throw new Error("Usage: agent-memory backlinks <name>");
+                process.stdout.write(toolFindBacklinks({ name }) + "\n");
+                return 0;
+            }
+            case "related": {
+                const name = positional[0];
+                if (!name)
+                    throw new Error("Usage: agent-memory related <name> [--max N]");
+                process.stdout.write(toolFindRelated({
+                    name,
+                    max: flags.max ? Number(flags.max) : undefined,
+                }) + "\n");
+                return 0;
+            }
             case "log": {
                 process.stdout.write(toolLogEvents({
                     tail: flags.tail ? Number(flags.tail) : undefined,
@@ -1100,15 +1703,17 @@ USAGE
   agent-memory-mcp                         MCP server mode (default when no args)
 
 COMMANDS
-  save <name> --type <t> --description <d> --content <c>
+  save <name> --type <t> --description <d> --content <c> [--tags "a,b,c"]
                                            Save or update a memory.
                                            Type: user | feedback | project | reference
                                            Content sources: --content "..." | --content-file <path> | --stdin
+                                           Tags: comma-separated, lowercase, max 40 chars each.
   search <query> [--limit N]               Fuzzy search (typo-tolerant), top N (default 10)
   relevant <query> [--max N]               Top N matches as full markdown for LLM ingestion
   get <name>                               Print one memory's full contents
-  list [--type <t>] [--offset N] [--limit N]
+  list [--type <t>] [--tags "a,b"] [--offset N] [--limit N]
                                            List memories (paginated, default limit 50)
+                                           Tag filter requires ALL listed tags (intersection).
   delete <name>                            Soft-delete: move to .trash/, removable later
   restore <name>                           Restore the most recent trash entry for <name>
   doctor [--rebuild-index]                 Check storage integrity (orphans, dangling
@@ -1117,6 +1722,12 @@ COMMANDS
   stats                                    Dashboard: counts per type, sizes, audit/trash counts.
   log [--tail N] [--action save|delete|restore]
                                            Recent audit-log entries.
+  verify <name>                            Re-evaluate a memory's claims (URLs, dates, file refs,
+                                           type-specific staleness heuristics). Static analysis;
+                                           no network calls.
+  backlinks <name>                         List memories that link to <name> via [[wiki-links]].
+  related <name> [--max N]                 Surface related memories via outbound + inbound links,
+                                           shared tags, type match, content similarity.
   import-claude-code [--source <path>] [--project <pat>] [--overwrite] [--dry-run]
                                            Walk ~/.claude/projects/*/memory/ and
                                            import each memory into the current store.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xultrax-web/agent-memory-mcp",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "mcpName": "io.github.xultrax-web/agent-memory-mcp",
   "description": "Markdown memory for AI agents. Plain files you can read, edit, grep, and commit. The only MCP memory server that isn't a database.",
   "type": "module",