@mnemoverse/mcp-memory-server 0.12.1 → 0.13.0

package/dist/tools.js

@@ -1,5 +1,5 @@
 /**
- * The ten memory tools, as one function any MCP server can register.
+ * The eleven tools (ten memory tools and vault_list), as one function any MCP server can register.
  *
  * ADR-025 (mnemoverse-core): this package defines the MCP surface, and every
  * server that exposes Mnemoverse memory over MCP registers the SAME tools from
@@ -12,14 +12,14 @@
  * or the environment.
  */
 import { z } from "zod";
-import { CURSOR_RE, formatReadItem, formatRecentPage, rawAuthorName, safeInline, structuredItem, } from "./render.js";
+import { CURSOR_RE, formatDateTag, formatReadItem, formatRecentPage, rawAuthorName, safeInline, structuredItem, } from "./render.js";
 // `NO_MATCH_MESSAGE` is no longer imported here: this file used to pick between
 // it and buildReadEmptyResponse by testing a note string for truthiness, which
 // is how "we could not check" came to be spelled like "the store is there".
 // Assembling the whole answer belongs in one place — src/teaching.ts.
 import { buildReadEmptyResponse } from "./teaching.js";
 import { classifyRooms, futureSinceNote, probeReadScope, readScopeNote, scopeLabel, } from "./scope.js";
-import { readRequestBody, recentRequestBody, writeRequestBody, searchedScope, } from "./requests.js";
+import { graphRequestBody, readRequestBody, recentRequestBody, writeRequestBody, searchedScope, } from "./requests.js";
 import { exactLiteral, formatDomainList, MAX_DOMAIN_LITERAL, MAX_DOMAIN_TAG_LITERAL, roomNamePhrase, structuredText, withDomainEscapeLegend, withEscapeLegendAt, } from "./names.js";
 import { ApiError, rewordFailure } from "./errors.js";
 // Field limits, generated from core's contract (src/limits.ts, ADR-025).
@@ -285,7 +285,9 @@ const PROBE_TIMEOUT_MS = 4000;
  * (test/read-structured.test.ts pins it unchanged).
  */
 const MEMORY_ITEM_OUTPUT = {
-    memory_id: z.string().describe("Identifier needed to rate or manage this saved memory."),
+    memory_id: z
+        .string()
+        .describe("Identifier needed to rate or manage this saved memory."),
     content: z.string().describe("Stored memory content."),
     domain: z.string().describe("User-defined memory namespace or domain."),
     created_at: z
@@ -298,14 +300,16 @@ const MEMORY_ITEM_OUTPUT = {
         .describe("Sanitized AGENT identity of the writer (never the human principal) — attribution in shared rooms."),
 };
 /**
- * Register the ten memory tools on `server`. Call once per server instance.
+ * Register the eleven tools on `server`. Call once per server instance.
  * `deps.apiFetch` is the only way the tools reach the API.
  */
 export function registerMemoryTools(server, deps) {
     const { wording, writeAuthor } = deps;
     // STEP4-2: `wording` reaches the error text here, on every rejection, not
     // in the consumer's constructors. See wordedApiFetch.
-    const apiFetch = wording === undefined ? deps.apiFetch : wordedApiFetch(deps.apiFetch, wording);
+    const apiFetch = wording === undefined
+        ? deps.apiFetch
+        : wordedApiFetch(deps.apiFetch, wording);
     // Read once, defensively: `wording` crosses a public package boundary a
     // caller controls only at compile time (STEP4-2, owner 2026-09-24). A
     // strict-equality check rather than a truthiness check, so any value other
@@ -320,10 +324,10 @@ export function registerMemoryTools(server, deps) {
     // ANNOTATIONS, decided once for every server that registers these tools
     // (owner, 2026-09-21; the stdio server and the hosted connector had answered
     // both opposite ways):
-    //  - openWorldHint is false on all ten. Every tool works on the user's own
+    //  - openWorldHint is false on all eleven. Every tool works on the user's own
     //    memory store and reaches nothing else; that the store sits behind an API
     //    does not make it an open world.
-    //  - destructiveHint is true only for a tool that deletes. None of these ten
+    //  - destructiveHint is true only for a tool that deletes. None of these eleven
     //    does. Rating a memory moves its ranking signals and never alters or
     //    erases what was saved (see memory_feedback).
     /**
@@ -349,7 +353,11 @@ export function registerMemoryTools(server, deps) {
      * wire, so the diagnosis can never describe a different store than the request.
      */
     function probeScope(searched) {
-        return probeReadScope(searched, () => apiFetch("/memory/stats", { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) }), () => apiFetch("/memory/rooms", { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) }), safeInline);
+        return probeReadScope(searched, () => apiFetch("/memory/stats", {
+            signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+        }), () => apiFetch("/memory/rooms", {
+            signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+        }), safeInline);
     }
     // --- Tool: memory_write ---
     server.registerTool("memory_write", {
@@ -402,7 +410,7 @@ export function registerMemoryTools(server, deps) {
             reason: z
                 .string()
                 .optional()
-                .describe("The memory service's own explanation of this outcome, quoted as sent — when stored is false this is the ONLY statement of WHY, e.g. \"Below importance threshold (0.047 < 0.1)\". Ordinary text is preserved exactly; only control, bidi, zero-width, and repeated-whitespace characters are normalized before display, and the value is capped at 400 characters. Absent when the service sent no explanation, or when nothing remains after that normalization."),
+                .describe('The memory service\'s own explanation of this outcome, quoted as sent — when stored is false this is the ONLY statement of WHY, e.g. "Below importance threshold (0.047 < 0.1)". Ordinary text is preserved exactly; only control, bidi, zero-width, and repeated-whitespace characters are normalized before display, and the value is capped at 400 characters. Absent when the service sent no explanation, or when nothing remains after that normalization.'),
             importance: z
                 .number()
                 .optional()
@@ -453,7 +461,9 @@ export function registerMemoryTools(server, deps) {
         // {@link WriteAuthor}), and this package cannot know the sixth field a
         // future core release adds any better than core's own validator does.
         const authorRaw = writeAuthor?.();
-        const author = typeof authorRaw === "object" && authorRaw !== null ? authorRaw : undefined;
+        const author = typeof authorRaw === "object" && authorRaw !== null
+            ? authorRaw
+            : undefined;
         const r = await apiFetch("/memory/write", {
             method: "POST",
             body: JSON.stringify(writeRequestBody({ content, concepts, domain }, author)),
@@ -501,7 +511,8 @@ export function registerMemoryTools(server, deps) {
         // exactly instead (src/names.ts). If it will not fit, say THAT rather than
         // drop the clause: omitting it would report a server that gave no reason.
         const reasonQuote = r?.reason
-            ? (exactLiteral(r.reason, 400)?.literal ?? "(too long to quote exactly)")
+            ? (exactLiteral(r.reason, 400)?.literal ??
+                "(too long to quote exactly)")
             : "";
         // Structured twins of the two text-only values above, for
         // `structuredContent`: the raw number instead of the two-decimal
@@ -518,7 +529,9 @@ export function registerMemoryTools(server, deps) {
             : undefined;
         const optionalStructured = {
             ...(reasonStructured === undefined ? {} : { reason: reasonStructured }),
-            ...(importanceStructured === undefined ? {} : { importance: importanceStructured }),
+            ...(importanceStructured === undefined
+                ? {}
+                : { importance: importanceStructured }),
         };
         // Narrowed to `true` by the guard above, so this is now the server's stated
         // verdict rather than "the body was not falsy".
@@ -683,7 +696,7 @@ export function registerMemoryTools(server, deps) {
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async ({ query, top_k, domain, order_by, since, until, exclude_author }) => {
+    }, async ({ query, top_k, domain, order_by, since, until, exclude_author, }) => {
         // ONE value, used for the request AND for every decision about it.
         //
         // A previous draft sent the raw string but decided the wording from a
@@ -704,7 +717,15 @@ export function registerMemoryTools(server, deps) {
         const searched = searchedScope(domain);
         const r = await apiFetch("/memory/read", {
             method: "POST",
-            body: JSON.stringify(readRequestBody({ query, top_k, domain, order_by, since, until, exclude_author })),
+            body: JSON.stringify(readRequestBody({
+                query,
+                top_k,
+                domain,
+                order_by,
+                since,
+                until,
+                exclude_author,
+            })),
         });
         // `items` must be a REAL array before anything below may speak. Core's
         // read response always carries one on a 200, so a body without it is not
@@ -1076,7 +1097,9 @@ export function registerMemoryTools(server, deps) {
                 // to the service either, so paging stops here and the page says
                 // the token could not be displayed (Copilot, #159).
                 position =
-                    typeof next === "string" && next && CURSOR_RE.test(next) ? next : undefined;
+                    typeof next === "string" && next && CURSOR_RE.test(next)
+                        ? next
+                        : undefined;
                 // No cursor: the feed ended, and the page says so. No entries: the
                 // server is not advancing, so continuing would spend requests on the
                 // same nothing. Ceiling reached: the caller's count is spent.
@@ -1232,7 +1255,8 @@ export function registerMemoryTools(server, deps) {
             // would pass the regex by coercion and then fail the schema.
             ...(acceptedCursor == null
                 ? { next_cursor: null }
-                : typeof acceptedCursor === "string" && CURSOR_RE.test(acceptedCursor)
+                : typeof acceptedCursor === "string" &&
+                    CURSOR_RE.test(acceptedCursor)
                     ? { next_cursor: acceptedCursor }
                     : {}),
         });
@@ -1273,23 +1297,17 @@ export function registerMemoryTools(server, deps) {
         "Report whether memories returned by memory_read were actually helpful. This is a learning signal, not a log: positive feedback raises a memory's ranking so it surfaces faster next time (across all of the user's tools), negative feedback lowers it so other memories out-rank it — nothing is erased and nothing decays with time. Call it right after you act on (or reject) recalled memories, passing the ids from the memory_read results as memory_ids. For memories read from a shared room, also pass that room's address as domain; your own memories need no domain. A read-only room member cannot rate the room's memories.",
         // `memory_ids` is the name (2026-09-21): the tool rates memories, which
         // is what every result is (an atom is the engine's word for its smallest
-        // unit), and the hosted connector already names the parameter so. Both
-        // fields are optional in the schema only so the handler can refuse the
-        // two ways a call can get this wrong with a sentence instead of a
-        // validation dump. Neither carries a format or a count cap: the engine
+        // unit), and the hosted connector already names the parameter so. The old
+        // name, atom_ids, was accepted alongside it from 0.11 and removed in
+        // 0.13 as announced; with one name left, memory_ids is schema-required.
+        // It carries no format or count cap: the engine
         // validates the ids and sets no maximum, and ADR-025 keeps such checks
         // with the engine rather than copying them here.
         inputSchema: {
             memory_ids: z
                 .array(z.string())
                 .min(1)
-                .optional()
-                .describe("Required: IDs of the memories to rate, the `id:` line of each memory_read result. (Optional in this schema only while the deprecated atom_ids is still accepted in its place.)"),
-            atom_ids: z
-                .array(z.string())
-                .min(1)
-                .optional()
-                .describe("Deprecated since 0.11, removed in 0.13: atom_ids is the old name of memory_ids, still accepted on its own until then. Pass memory_ids instead."),
+                .describe("IDs of the memories to rate, the `id:` line of each memory_read result."),
             outcome: z
                 .number()
                 .min(CORE_LIMITS.feedbackOutcome.minimum)
@@ -1354,34 +1372,8 @@ export function registerMemoryTools(server, deps) {
             idempotentHint: false,
             openWorldHint: false,
         },
-    }, async ({ memory_ids, atom_ids: legacyIds, outcome, domain }) => {
-        // Both names at once is ambiguous (which list did the caller mean?), so
-        // it is refused rather than resolved by a silent preference.
-        if (memory_ids !== undefined && legacyIds !== undefined) {
-            return {
-                isError: true,
-                content: [
-                    {
-                        type: "text",
-                        text: "Pass the ids as memory_ids only. atom_ids is its old name, still " +
-                            "accepted on its own, but both at once is ambiguous. Nothing was rated.",
-                    },
-                ],
-            };
-        }
-        const atom_ids = memory_ids ?? legacyIds;
-        if (atom_ids === undefined) {
-            return {
-                isError: true,
-                content: [
-                    {
-                        type: "text",
-                        text: "memory_feedback needs memory_ids: the ids from the memory_read results " +
-                            "you are rating. Nothing was rated.",
-                    },
-                ],
-            };
-        }
+    }, async ({ memory_ids, outcome, domain }) => {
+        const atom_ids = memory_ids;
         // `atom_ids` below is the ENGINE's field name for the same list; the
         // wire contract is unchanged. `domain` goes through `searchedScope`, as
         // on memory_read and memory_list_recent: an empty string counts as no
@@ -1391,7 +1383,9 @@ export function registerMemoryTools(server, deps) {
         const scope = searchedScope(domain);
         const r = await apiFetch("/memory/feedback", {
             method: "POST",
-            body: JSON.stringify(scope === undefined ? { atom_ids, outcome } : { atom_ids, outcome, domain: scope }),
+            body: JSON.stringify(scope === undefined
+                ? { atom_ids, outcome }
+                : { atom_ids, outcome, domain: scope }),
         });
         // A FIELD THE SERVER DID NOT SEND IS UNKNOWN, NOT ZERO — the rule
         // memory_stats already applies with `num()`, broken here by
@@ -1416,7 +1410,9 @@ export function registerMemoryTools(server, deps) {
         // isSafeInteger, not isInteger: the output schema is z.number().int(),
         // and zod 4 rejects an integer above 2^53 - 1, so such a count would
         // turn the whole reply into an SDK validation error (review, 2026-09-23).
-        typeof reported === "number" && Number.isSafeInteger(reported) && reported >= 0
+        typeof reported === "number" &&
+            Number.isSafeInteger(reported) &&
+            reported >= 0
             ? reported
             : undefined;
         // Structured twin of the text's average-valence clause built further
@@ -1491,7 +1487,8 @@ export function registerMemoryTools(server, deps) {
                         text: `${sent} The service accepted the call but did not report how many ` +
                             `memories it updated, so whether any changed is unknown from here. ` +
                             `That is not evidence of a failure — do not re-send the same rating ` +
-                            `on the strength of it.` + pickADirection,
+                            `on the strength of it.` +
+                            pickADirection,
                     },
                 ],
             };
@@ -1512,8 +1509,12 @@ export function registerMemoryTools(server, deps) {
             return structured("No feedback was recorded — none of those ids matched a memory " +
                 `${feedbackScope(scope)}. ${feedbackMissCauses(scope)}`, {
                 updated_count: 0,
-                ...(avgValenceStructured === undefined ? {} : { avg_valence: avgValenceStructured }),
-                ...(coactivationEdges === undefined ? {} : { coactivation_edges: coactivationEdges }),
+                ...(avgValenceStructured === undefined
+                    ? {}
+                    : { avg_valence: avgValenceStructured }),
+                ...(coactivationEdges === undefined
+                    ? {}
+                    : { coactivation_edges: coactivationEdges }),
             });
         }
         // WHOSE NUMBER THIS IS (#68). `updated_count` is the count of memories the
@@ -1531,11 +1532,11 @@ export function registerMemoryTools(server, deps) {
         const effect = outcome > 0
             ? " — they should surface sooner next time."
             : outcome < 0
-                // No fade. 0.9.1 (#95) withdrew "lets it fade" as false — nothing
-                // time-decays, nothing is auto-deleted, and deletion has been
-                // administrative-only since 0.9.0 — and this line kept promising it
-                // after the release that deleted the claim from the README.
-                ? " — they should rank lower next time. Out-ranked, not erased: nothing is deleted and nothing decays with time."
+                ? // No fade. 0.9.1 (#95) withdrew "lets it fade" as false — nothing
+                    // time-decays, nothing is auto-deleted, and deletion has been
+                    // administrative-only since 0.9.0 — and this line kept promising it
+                    // after the release that deleted the claim from the README.
+                    " — they should rank lower next time. Out-ranked, not erased: nothing is deleted and nothing decays with time."
                 : ".";
         // WHAT THE COUNT IS NOT: a guarantee that every id landed. `atom_ids.length`
         // was never compared with it, so five ids and `updated_count: 2` printed
@@ -1590,8 +1591,12 @@ export function registerMemoryTools(server, deps) {
         // resumed it afterwards.
         return structured(`${sent} The service reports ${noun} updated${effect}${valence}${mismatch}${pickADirection}`, {
             updated_count: count,
-            ...(avgValenceStructured === undefined ? {} : { avg_valence: avgValenceStructured }),
-            ...(coactivationEdges === undefined ? {} : { coactivation_edges: coactivationEdges }),
+            ...(avgValenceStructured === undefined
+                ? {}
+                : { avg_valence: avgValenceStructured }),
+            ...(coactivationEdges === undefined
+                ? {}
+                : { coactivation_edges: coactivationEdges }),
         });
     });
     // --- Tool: memory_stats ---
@@ -1678,8 +1683,8 @@ export function registerMemoryTools(server, deps) {
         // "0" is the same class of lie as an empty search claiming emptiness:
         // "Associations: 0" reads as "this memory has learned nothing", which is
         // a strong and possibly false statement about the product itself.
-        const num = (v) => (typeof v === "number" ? String(v) : "unknown");
-        const dec = (v) => (typeof v === "number" ? v.toFixed(2) : "unknown");
+        const num = (v) => typeof v === "number" ? String(v) : "unknown";
+        const dec = (v) => typeof v === "number" ? v.toFixed(2) : "unknown";
         // THE surface this tool's own description sends the reader to, to
         // confirm the exact domain name before writing to it — so it has to be
         // able to answer that. (Until 2026-08-20 memory_delete_domain also sent
@@ -1733,7 +1738,9 @@ export function registerMemoryTools(server, deps) {
         // whatever num()/dec() print for the same malformed value, and that
         // text/data divergence is disclosed in the CHANGELOG, as S5 disclosed
         // its cursor semantics.
-        const safeIntOrUndefined = (v) => typeof v === "number" && Number.isSafeInteger(v) && v >= 0 ? v : undefined;
+        const safeIntOrUndefined = (v) => typeof v === "number" && Number.isSafeInteger(v) && v >= 0
+            ? v
+            : undefined;
         const finiteOrUndefined = (v) => typeof v === "number" && Number.isFinite(v) ? v : undefined;
         const episodesStructured = safeIntOrUndefined(r?.episodes);
         const prototypesStructured = safeIntOrUndefined(r?.prototypes);
@@ -1777,12 +1784,18 @@ export function registerMemoryTools(server, deps) {
         withDomainEscapeLegend(capResult(text, "The domain list was truncated — some domain names are not shown."), ...(Array.isArray(r?.domains) ? r.domains : [])), {
             memory_count: memoryCount,
             domains: domainsStructured,
-            ...(episodesStructured === undefined ? {} : { episodes: episodesStructured }),
-            ...(prototypesStructured === undefined ? {} : { prototypes: prototypesStructured }),
+            ...(episodesStructured === undefined
+                ? {}
+                : { episodes: episodesStructured }),
+            ...(prototypesStructured === undefined
+                ? {}
+                : { prototypes: prototypesStructured }),
             ...(hebbianEdgesStructured === undefined
                 ? {}
                 : { hebbian_edges: hebbianEdgesStructured }),
-            ...(avgValenceStructured === undefined ? {} : { avg_valence: avgValenceStructured }),
+            ...(avgValenceStructured === undefined
+                ? {}
+                : { avg_valence: avgValenceStructured }),
             ...(avgImportanceStructured === undefined
                 ? {}
                 : { avg_importance: avgImportanceStructured }),
@@ -1948,7 +1961,10 @@ export function registerMemoryTools(server, deps) {
         },
         outputSchema: {
             share_message: z.string().describe("Ready-to-forward invite text."),
-            join_url: z.string().optional().describe("Landing URL the invitee can open to join."),
+            join_url: z
+                .string()
+                .optional()
+                .describe("Landing URL the invitee can open to join."),
             code: z
                 .string()
                 .optional()
@@ -1958,7 +1974,11 @@ export function registerMemoryTools(server, deps) {
                 .string()
                 .optional()
                 .describe("The room's domain address (xroom:<id>)."),
-            expires_at: z.string().nullable().optional().describe("ISO 8601 expiry, or null."),
+            expires_at: z
+                .string()
+                .nullable()
+                .optional()
+                .describe("ISO 8601 expiry, or null."),
         },
         annotations: {
             title: "Invite to room",
@@ -1995,7 +2015,10 @@ export function registerMemoryTools(server, deps) {
         // structuredContent.share_message to pair it with.
         const shareMessageStructured = structuredText(rawMessage, 800);
         if (shareMessageStructured === undefined) {
-            return { content: [{ type: "text", text }], isError: true };
+            return {
+                content: [{ type: "text", text }],
+                isError: true,
+            };
         }
         // `join_url` through safeInline with the connector's own cap of 400,
         // as the connector does (mnemoverse-mcp-remote, memory_invite_to_room):
@@ -2021,21 +2044,33 @@ export function registerMemoryTools(server, deps) {
         // structured consumer lands on the instant this client used rather than
         // reading the naive string as local time (CodeRabbit, review round 2).
         // `null` when core sent null; absent when the value does not parse.
-        const expiresAtStructured = r?.expires_at === null ? null : (utcInstant(r?.expires_at) ?? undefined);
+        const expiresAtStructured = r?.expires_at === null
+            ? null
+            : (utcInstant(r?.expires_at) ?? undefined);
         return structured(text, {
             share_message: shareMessageStructured,
-            ...(joinUrlStructured === undefined ? {} : { join_url: joinUrlStructured }),
+            ...(joinUrlStructured === undefined
+                ? {}
+                : { join_url: joinUrlStructured }),
             ...(codeStructured === undefined ? {} : { code: codeStructured }),
             ...(scopeStructured === undefined ? {} : { scope: scopeStructured }),
-            ...(roomAddressStructured === undefined ? {} : { room_address: roomAddressStructured }),
-            ...(expiresAtStructured === undefined ? {} : { expires_at: expiresAtStructured }),
+            ...(roomAddressStructured === undefined
+                ? {}
+                : { room_address: roomAddressStructured }),
+            ...(expiresAtStructured === undefined
+                ? {}
+                : { expires_at: expiresAtStructured }),
         });
     });
     // --- Tool: memory_join_room ---
     server.registerTool("memory_join_room", {
         description: "Join a shared memory room using an invite code (starts with 'mnvr_'). Use when the user pastes an invite code or says something like 'join room with code ...'. After joining, use the returned address as the `domain` on memory_read to read the shared room — the result tells you what you may do with it: memory_write to that address is only allowed when your membership scope is read_write; a read-only membership has that write refused; and when the server does not report a scope, whether memory_write would succeed is stated as unknown rather than promised either way.",
         inputSchema: {
-            code: z.string().min(1).max(200).describe("The invite code (mnvr_...)."),
+            code: z
+                .string()
+                .min(1)
+                .max(200)
+                .describe("The invite code (mnvr_...)."),
         },
         outputSchema: {
             room_id: z.string().describe("The room's id (room_...)."),
@@ -2043,7 +2078,10 @@ export function registerMemoryTools(server, deps) {
                 .string()
                 .describe("Domain address (xroom:<id>); pass as `domain` on read/write."),
             name: z.string().optional().describe("The room name."),
-            scope: z.string().optional().describe("Your role in the room ('read' | 'read_write')."),
+            scope: z
+                .string()
+                .optional()
+                .describe("Your role in the room ('read' | 'read_write')."),
             already_member: z
                 .boolean()
                 .optional()
@@ -2173,7 +2211,9 @@ export function registerMemoryTools(server, deps) {
                     .describe("Domain address (xroom:<id>); pass as `domain` on read/write."),
                 role: z.string().describe("'owner' or 'member'."),
                 scope: z.string().optional().describe("'read' or 'read_write'."),
-                archived: z.boolean().describe("True if archived (owned rooms only)."),
+                archived: z
+                    .boolean()
+                    .describe("True if archived (owned rooms only)."),
             })),
         },
         annotations: {
@@ -2290,7 +2330,8 @@ export function registerMemoryTools(server, deps) {
                 droppedRooms += 1;
                 continue;
             }
-            const nameStructured = typeof r?.name === "string" && exactLiteral(r.name, MAX_DOMAIN_LITERAL)
+            const nameStructured = typeof r?.name === "string" &&
+                exactLiteral(r.name, MAX_DOMAIN_LITERAL)
                 ? structuredText(r.name, MAX_DOMAIN_LITERAL)
                 : undefined;
             roomsStructured.push({
@@ -2368,7 +2409,9 @@ export function registerMemoryTools(server, deps) {
                 alias: z
                     .string()
                     .describe("The secret's alias — the reference you use, never the value."),
-                context: z.string().describe("The secret's purpose/context — never the value."),
+                context: z
+                    .string()
+                    .describe("The secret's purpose/context — never the value."),
                 concepts: z.array(z.string()).describe("Concept tags."),
             })),
         },
@@ -2391,7 +2434,9 @@ export function registerMemoryTools(server, deps) {
             return unreadableAnswerReply("The secret list", "a list of your Vault secrets", "none are stored");
         }
         if (list.length === 0) {
-            return structured("No secrets are stored in your Vault yet.", { secrets: [] });
+            return structured("No secrets are stored in your Vault yet.", {
+                secrets: [],
+            });
         }
         const lines = list.map((s) => {
             const alias = safeInline(s?.alias) || "(no alias)";
@@ -2418,12 +2463,17 @@ export function registerMemoryTools(server, deps) {
             const concepts = Array.isArray(conceptsRaw)
                 ? conceptsRaw.map((c) => structuredText(c, VAULT_CONCEPT_CAP))
                 : undefined;
-            const conceptsOk = concepts !== undefined && concepts.every((c) => c !== undefined);
+            const conceptsOk = concepts !== undefined &&
+                concepts.every((c) => c !== undefined);
             if (alias === undefined || context === undefined || !conceptsOk) {
                 droppedSecrets += 1;
                 continue;
             }
-            secretsStructured.push({ alias, context, concepts: concepts });
+            secretsStructured.push({
+                alias,
+                context,
+                concepts: concepts,
+            });
         }
         if (droppedSecrets > 0) {
             console.error(`Mnemoverse: vault_list dropped ${droppedSecrets} malformed secret ` +
@@ -2433,5 +2483,226 @@ export function registerMemoryTools(server, deps) {
         }
         return structured(finalText, { secrets: secretsStructured });
     });
+    // --- Tool: memory_graph ---
+    server.registerTool("memory_graph", {
+        description: "Reads the association edges around given concepts: which concepts the memory has linked together, with each link's weight, outcome valence and co-activation count. Use to inspect what a memory store has learned or to explain why a read expanded to a concept. Read-only.",
+        inputSchema: {
+            // Bounds come from CORE_LIMITS (src/limits.ts, ADR-025) EXCEPT the
+            // per-seed 200-character cap: GraphRequestSchema.seeds.items carries
+            // no maxLength in the published JSON Schema at all (core enforces it
+            // with a Pydantic validator that has no JSON-Schema-expressible
+            // form, unlike writeContent/domain/etc.), so there is no numeric
+            // field for scripts/generate-limits.mjs to fetch — that literal
+            // stays inline, same as recentCursor's is generated but this one
+            // cannot be.
+            seeds: z
+                .array(z
+                .string()
+                // CODE-POINT length, not `.max(200)` (Copilot review, round 2):
+                // zod's `.max()` on a string counts UTF-16 CODE UNITS, and
+                // core's 200-char/VARCHAR(200) bound counts Unicode CHARACTERS
+                // — 200 astral characters (many emoji, some CJK-extension
+                // ideographs) are 400 UTF-16 units and would be rejected here
+                // while remaining a valid seed core would accept. `[...s]`
+                // iterates by code point, the same technique `structuredText`
+                // and `capResult`'s hint already use (src/names.ts, src/tools.ts).
+                .refine((s) => [...s].length <= 200, {
+                message: "must be at most 200 characters",
+            })
+                .refine((s) => s.trim().length > 0, {
+                message: "must not be blank",
+            }))
+                .min(CORE_LIMITS.graphSeeds.minItems)
+                .max(CORE_LIMITS.graphSeeds.maxItems)
+                .describe("Concepts to center the graph on (1-20, each ≤200 chars, non-blank) — e.g. ['deploy', 'staging']. An unrecognised concept simply contributes no edges; it is not an error."),
+            depth: z
+                .number()
+                .int()
+                .min(CORE_LIMITS.graphDepth.minimum)
+                .max(CORE_LIMITS.graphDepth.maximum)
+                .optional()
+                .describe("Hops to expand from the seeds (1-3, default 1). At depth 2 or 3, if min_weight is omitted the engine floors edge weight at 0.05 at EVERY hop — including the first — so a hub concept cannot fan out across the whole store before limit applies; pass min_weight explicitly (0 included) to see every edge anyway."),
+            domain: z
+                .string()
+                .optional()
+                .describe("Read a shared room's graph instead of your own: pass that room's address (e.g. 'xroom:room_01ABC'). Find room addresses with memory_list_rooms. Unlike memory_read, any OTHER value has no effect here — the association store has no domain column, so a plain domain name behaves exactly like omitting this field."),
+            min_weight: z
+                .number()
+                .finite()
+                .min(CORE_LIMITS.graphMinWeight.minimum)
+                .optional()
+                .describe("Only include edges at or above this weight (≥ 0). Omit for no floor at depth 1; at depth 2/3 the engine applies its own 0.05 floor when this is omitted (see depth) — pass 0 to see every edge at every depth."),
+            limit: z
+                .number()
+                .int()
+                .min(CORE_LIMITS.graphLimit.minimum)
+                .max(CORE_LIMITS.graphLimit.maximum)
+                .optional()
+                .describe("Max edges to return (1-500, default 100 — mirrors memory_read's top_k bounds)."),
+        },
+        // Field names and descriptions follow core's GraphNodeSchema/GraphEdgeSchema
+        // (https://core.mnemoverse.com/openapi.json) directly — this is a new
+        // endpoint with no back-compat surface, so there is no prior wire shape to
+        // reconcile the way memory_read's MEMORY_ITEM_OUTPUT does.
+        outputSchema: {
+            nodes: z
+                .array(z.object({
+                concept: z.string().describe("The concept name."),
+                degree: z
+                    .number()
+                    .int()
+                    .describe("Edges in THIS response touching this concept — not its total degree across the whole store, which limit/truncated may cut short."),
+            }))
+                .describe("Concepts touched by edges below. A seed with no surviving edge (unrecognised concept, or every edge fell below the weight floor) is not listed."),
+            edges: z
+                .array(z.object({
+                source: z
+                    .string()
+                    .describe("One side of the edge (storage order, not learn order)."),
+                target: z
+                    .string()
+                    .describe("The other side of the edge (storage order, not learn order)."),
+                weight: z.number().describe("Co-activation strength, 0 and up."),
+                valence: z.number().describe("Outcome polarity, -1 to 1."),
+                count: z.number().int().describe("Co-activation count."),
+                updated_at: z
+                    .string()
+                    .describe("UTC instant this edge was last reinforced."),
+            }))
+                .describe("Association edges found within the requested depth."),
+            truncated: z
+                .boolean()
+                .describe("True when a per-hop server cap or limit cut the walk short — the store may hold more edges than are reported here."),
+            min_weight_applied: z
+                .number()
+                .describe("The weight floor actually used at every hop: your min_weight when you set one (0 included); otherwise 0.05 from depth 2, or 0 at depth 1."),
+        },
+        annotations: {
+            title: "Association graph",
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ seeds, depth, domain, min_weight, limit }) => {
+        const r = await apiFetch("/memory/graph", {
+            method: "POST",
+            body: JSON.stringify(graphRequestBody({ seeds, depth, domain, min_weight, limit })),
+        });
+        // core's GraphResponseSchema sends all four of these on every 200
+        // (nodes, edges, truncated, min_weight_applied are all required) — the
+        // same "unreadable 2xx" class memory_read's item guard catches one
+        // level up, here for the whole response shape and for each edge/node.
+        // All-or-nothing, like memory_write's atom_id guard: there is no honest
+        // partial rendering of a graph this client could not fully validate.
+        const nodesRaw = r?.nodes;
+        const edgesRaw = r?.edges;
+        const truncatedRaw = r?.truncated;
+        const minWeightAppliedRaw = r?.min_weight_applied;
+        const shapeOk = Array.isArray(nodesRaw) &&
+            Array.isArray(edgesRaw) &&
+            typeof truncatedRaw === "boolean" &&
+            typeof minWeightAppliedRaw === "number" &&
+            Number.isFinite(minWeightAppliedRaw) &&
+            // `degree`/`count` are safe-integer checks, not just finite ones:
+            // the outputSchema declares both `z.number().int()` (CodeRabbit
+            // review, round 1), and zod 4 rejects a non-integer AND an integer
+            // above 2^53 - 1 there — the same reasoning memory_feedback's
+            // `updated_count` guard already documents. `weight`/`valence` stay
+            // finite-only: their outputSchema is plain `z.number()`.
+            nodesRaw.every((n) => typeof n?.concept === "string" &&
+                typeof n?.degree === "number" &&
+                Number.isSafeInteger(n.degree)) &&
+            edgesRaw.every((e) => typeof e?.source === "string" &&
+                typeof e?.target === "string" &&
+                typeof e?.weight === "number" &&
+                Number.isFinite(e.weight) &&
+                typeof e?.valence === "number" &&
+                Number.isFinite(e.valence) &&
+                typeof e?.count === "number" &&
+                Number.isSafeInteger(e.count) &&
+                typeof e?.updated_at === "string");
+        if (!shapeOk) {
+            return unreadableAnswerReply("The graph result", "a set of association edges", "these concepts have no associations");
+        }
+        const nodes = nodesRaw;
+        const edges = edgesRaw;
+        const truncated = truncatedRaw;
+        const minWeightApplied = minWeightAppliedRaw;
+        const hops = depth ?? 1;
+        // Computed BEFORE the empty-edges branch and shared with the non-empty
+        // one below (Copilot review, round 2): the early return used to skip
+        // both notes entirely, so a truncated, all-below-floor answer (0 edges
+        // survived the cut) told a text-only reader only "no association edges
+        // found" — indistinguishable from a genuinely quiet concept.
+        const truncatedNote = truncated
+            ? "\n\n(truncated — the store may hold more edges than this call " +
+                "reached; core does not promise these are sorted by weight before " +
+                "the cut, so a higher min_weight, not a lower limit, is what " +
+                "reliably narrows to the strongest ones)"
+            : "";
+        const floorAttribution = min_weight === undefined
+            ? "the engine's own floor at this depth"
+            : "the min_weight you passed";
+        const floorNote = minWeightApplied > 0
+            ? `\n\n(edges below weight ${minWeightApplied} were excluded — ${floorAttribution})`
+            : "";
+        if (edges.length === 0) {
+            return structured(`No association edges found for ${seeds.length === 1 ? "this seed" : "these seeds"} ` +
+                `within ${hops} hop${hops === 1 ? "" : "s"}` +
+                (minWeightApplied > 0
+                    ? ` at or above weight ${minWeightApplied}`
+                    : "") +
+                `.` +
+                truncatedNote +
+                floorNote, { nodes, edges, truncated, min_weight_applied: minWeightApplied });
+        }
+        // Sorted by weight, strongest first (the brief for this tool, and the
+        // one ranking a reader can act on — core does not promise the wire
+        // order is anything in particular). structuredContent.edges (below)
+        // deliberately keeps the SERVER's order — only this rendered `lines`
+        // array is reordered (llms.txt says so explicitly, Copilot round 2).
+        const sorted = [...edges].sort((a, b) => b.weight - a.weight);
+        // `-0.00` guard, same fix memory_feedback's avg_valence carries
+        // (CodeRabbit on #146): valence can be negative and round to zero.
+        const fmtSigned = (n) => n.toFixed(2).replace(/^-0\.00$/, "0.00");
+        // Concept names are NOT this client's own text (CN-032): in a shared
+        // room they are whatever concept another member's memory_write
+        // supplied, so a newline or instruction-shaped string in `source`/
+        // `target` must not be interpolated raw into text a DIFFERENT
+        // principal's model then reads (Copilot review, round 1). Printed as
+        // an exact JSON literal (src/names.ts), the same treatment `@domain`
+        // and `[by "name"]` already get — not `safeInline`, which maps every
+        // non-ASCII `\w`-excluded character to a space and would silently
+        // erase a Cyrillic/CJK concept name the way it once erased author
+        // names (issue #66). `structuredContent` still carries the raw value
+        // (below): only the rendered TEXT needs the escape treatment.
+        const nameLiteral = (s) => exactLiteral(s, MAX_DOMAIN_LITERAL)?.literal ??
+            "(name cannot be printed exactly)";
+        const lines = sorted.map((e, i) => `${i + 1}. ${nameLiteral(e.source)} — ${nameLiteral(e.target)} ` +
+            `(weight: ${e.weight.toFixed(2)}, valence: ${fmtSigned(e.valence)}, ` +
+            `count: ${e.count})${formatDateTag(e.updated_at)}`);
+        const header = `${edges.length} association edge${edges.length === 1 ? "" : "s"} found` +
+            (minWeightApplied > 0 ? ` (weight ≥ ${minWeightApplied})` : "") +
+            ":";
+        // The two status notes go BEFORE the edge lines, not after them: the
+        // cap truncates from the end, so a page long enough to be cut would
+        // otherwise lose exactly the lines that say it is incomplete and what
+        // floor applied (CodeRabbit on #174, after the 0.12.1 merge). Legend
+        // appended AFTER capResult, like memory_read's, for the same reason.
+        const notes = truncatedNote + floorNote;
+        const preface = notes ? header + notes + "\n" : header;
+        const text = withDomainEscapeLegend(capResult([preface, ...lines].join("\n"), "Lower `limit` or raise `min_weight` to see fewer edges."), ...edges.flatMap((e) => [e.source, e.target]));
+        // structuredContent carries the validated nodes/edges EXACTLY, uncapped
+        // and unescaped (OD-11, the same rule memory_read's items get): a
+        // client reading structured data reads these as the graph, not as a
+        // rendering of it.
+        return structured(text, {
+            nodes,
+            edges,
+            truncated,
+            min_weight_applied: minWeightApplied,
+        });
+    });
 }
 //# sourceMappingURL=tools.js.map