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

package/README.md

@@ -198,6 +198,8 @@ Custom path:
 | `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
 
@@ -219,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
@@ -242,6 +261,10 @@ agent-memory stats                             # dashboard: counts, sizes, audit
 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
@@ -349,9 +372,16 @@ This server is built to be used daily, not to demo well once.
 - **`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).
 
-**Landing in v0.8 - v0.9:**
+**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+:**
 
-- Tags + wiki-links + folder support + `find_related` (organization-at-scale)
+- 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

@@ -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,21 +287,29 @@ 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);
@@ -344,16 +403,21 @@ function toolGetMemory(args) {
     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();
@@ -361,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) {
@@ -718,6 +795,124 @@ function toolVerifyMemory(args) {
     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) {
@@ -827,7 +1022,7 @@ function actionColor(action) {
 // -------------------------------------------------------------
 // Server wiring
 // -------------------------------------------------------------
-const server = new Server({ name: "agent-memory", version: "0.7.0" }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
+const server = new Server({ name: "agent-memory", version: "0.8.0" }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
 // -------------------------------------------------------------
 // Resource URI scheme
 // -------------------------------------------------------------
@@ -1077,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"],
             },
@@ -1124,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: {
@@ -1133,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)." },
                 },
@@ -1203,6 +1408,32 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 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) => {
@@ -1243,6 +1474,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             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}`);
         }
@@ -1276,6 +1513,8 @@ const CLI_COMMANDS = new Set([
     "stats",
     "log",
     "verify",
+    "backlinks",
+    "related",
     "import-claude-code",
     "help",
     "--help",
@@ -1344,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;
@@ -1378,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");
@@ -1412,6 +1653,23 @@ async function cliMain(command, rest) {
                 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,
@@ -1445,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
@@ -1465,6 +1725,9 @@ COMMANDS
   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.7.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",