@mnemoverse/mcp-memory-server 0.11.0 → 0.12.1

package/dist/tools.js

@@ -12,7 +12,7 @@
  * or the environment.
  */
 import { z } from "zod";
-import { CURSOR_RE, formatReadItem, formatRecentPage, safeInline, structuredItem, } from "./render.js";
+import { CURSOR_RE, 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".
@@ -20,14 +20,43 @@ import { CURSOR_RE, formatReadItem, formatRecentPage, safeInline, structuredItem
 import { buildReadEmptyResponse } from "./teaching.js";
 import { classifyRooms, futureSinceNote, probeReadScope, readScopeNote, scopeLabel, } from "./scope.js";
 import { readRequestBody, recentRequestBody, writeRequestBody, searchedScope, } from "./requests.js";
-import { exactLiteral, formatDomainList, roomNamePhrase, structuredText, withDomainEscapeLegend, } from "./names.js";
-import { ApiError } from "./errors.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).
 import { CORE_LIMITS } from "./limits.js";
+// For the invite's `expires_at` (S8, structured-output plan): the same
+// UTC-instant reader src/render.ts uses for a memory's `created_at`.
+import { utcInstant } from "./time.js";
+/**
+ * `deps.apiFetch` with `deps.wording` applied to what it throws (STEP4-2):
+ * every rejection passes through {@link rewordFailure}, so an `ApiError`,
+ * `NetworkError` or `UnreadableBodyError` the consumer built with no
+ * `wording` (or with a different one) reaches the model explained under the
+ * wording this registration was given. Results and every other rejection
+ * pass through untouched. Installed only when `wording` is supplied at all:
+ * the stdio server supplies none, and its `apiFetch` is used exactly as
+ * before.
+ */
+export function wordedApiFetch(inner, wording) {
+    return async (path, options) => {
+        try {
+            return await inner(path, options);
+        }
+        catch (e) {
+            throw rewordFailure(e, wording);
+        }
+    };
+}
 // Hard cap on tool result size — required by Claude Connectors Directory
 // (https://support.claude.com/en/articles/12922490-remote-mcp-server-submission-guide).
 // Approximate token count = chars / 4. Cap at 24,000 tokens to leave headroom under the 25K limit.
-const MAX_RESULT_CHARS = 24_000 * 4;
+//
+// Exported (re-exported from ./shared, ADR-025) so a future editor does not
+// move or rename it without checking there: it is now the one cap both this
+// server and, from step 4 of the structured-output plan, the hosted connector
+// apply to a tool result's text. `structuredContent` is NOT capped (OD-11,
+// 2026-09-23); this bound is text-only.
+export const MAX_RESULT_CHARS = 24_000 * 4;
 /**
  * Truncate a result string to MAX_RESULT_CHARS, appending a notice if truncated.
  * Required by Claude Connectors Directory submission policy.
@@ -36,8 +65,12 @@ const MAX_RESULT_CHARS = 24_000 * 4;
  * before the cut point is a high surrogate (U+D800–U+DBFF), drop it so the
  * result stays well-formed. Otherwise an emoji or non-BMP character at the
  * boundary can produce a lone surrogate and corrupt downstream JSON encoding.
+ *
+ * Exported (re-exported from ./shared) so a consumer applying MAX_RESULT_CHARS
+ * to its own tool results does not have to re-implement this code-point-safe
+ * truncation as a plain `slice`, which can cut a surrogate pair.
  */
-function capResult(text, 
+export function capResult(text, 
 // The default recommends ONLY the control that works. A previous draft also
 // said "or smaller top_k" — but top_k is not a hard cap (association
 // expansion can return more, the relevance floor fewer; the same query at
@@ -46,16 +79,30 @@ function capResult(text,
 moreHint = "Use a more specific query to see all results.") {
     if (text.length <= MAX_RESULT_CHARS)
         return text;
-    let truncated = text.slice(0, MAX_RESULT_CHARS - 200);
+    // `moreHint` lets no-input tools (the discovery lists) give accurate truncation
+    // guidance instead of the read-tool default (which points at a query control a
+    // repeated no-arg call cannot use). Existing callers keep the default message.
+    //
+    // The reserve for the notice is 200 characters, as it always was, so every
+    // existing truncated result keeps its exact cut; a hint longer than that
+    // reserve (a consumer of the /shared export may pass any sentence) widens
+    // the reserve to the suffix's own length instead of pushing the result over
+    // the cap, and a hint is bounded at MAX_HINT_CODE_POINTS so the suffix can
+    // never be the whole budget (review round 2 on the export, CodeRabbit).
+    const hint = [...moreHint].slice(0, MAX_HINT_CODE_POINTS).join("");
+    const suffix = `\n\n[…truncated to fit the 25K token limit. ${hint}]`;
+    const reserve = Math.max(200, suffix.length);
+    let truncated = text.slice(0, MAX_RESULT_CHARS - reserve);
     const lastCode = truncated.charCodeAt(truncated.length - 1);
     if (lastCode >= 0xd800 && lastCode <= 0xdbff) {
         truncated = truncated.slice(0, -1);
     }
-    // `moreHint` lets no-input tools (the discovery lists) give accurate truncation
-    // guidance instead of the read-tool default (which points at a query control a
-    // repeated no-arg call cannot use). Existing callers keep the default message.
-    return `${truncated}\n\n[…truncated to fit the 25K token limit. ${moreHint}]`;
+    return `${truncated}${suffix}`;
 }
+/** The longest `moreHint` capResult will print; the rest is cut, so the suffix
+ * cannot take the whole result budget. 1,000 code points is ten times the
+ * longest hint this package passes. */
+const MAX_HINT_CODE_POINTS = 1_000;
 /**
  * A 2xx whose body does not carry what core always sends for this operation.
  *
@@ -255,7 +302,21 @@ const MEMORY_ITEM_OUTPUT = {
  * `deps.apiFetch` is the only way the tools reach the API.
  */
 export function registerMemoryTools(server, deps) {
-    const { apiFetch } = 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);
+    // 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
+    // than the one literal "this connector" (including a typo, a boolean, or
+    // a stale value from a future third option) falls back to the default
+    // rather than being printed. Defaults to today's wording exactly, so a
+    // server that supplies no `wording` at all gets byte-identical descriptions.
+    const serverNoun = wording?.serverNoun === "this connector" ? "this connector" : "this server";
+    // Same value, sentence-initial capitalisation, for the one description that
+    // opens a second sentence with it rather than sitting mid-clause.
+    const serverNounCap = serverNoun === "this connector" ? "This connector" : "This server";
     // 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):
@@ -380,9 +441,22 @@ export function registerMemoryTools(server, deps) {
         // returns, needs room addresses deliberately EXEMPT and zero-width
         // characters handled (JS trim() does not strip them — verified, contrary
         // to what an earlier comment here asserted).
+        //
+        // `writeAuthor` (STEP4-5): called once, here, only for this one write,
+        // never for a read or a probe. `typeof` first, not a shape check: this
+        // dependency crosses a public package boundary a caller controls only
+        // at compile time, so a runtime value that is not an object (a string,
+        // a number, `null`) is treated the same as "no author", rather than
+        // reaching JSON.stringify as a field core would then have to reject.
+        // Whatever IS an object is sent exactly as returned: no field-level
+        // normalisation here, because core re-normalises server-side (see
+        // {@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 r = await apiFetch("/memory/write", {
             method: "POST",
-            body: JSON.stringify(writeRequestBody({ content, concepts, domain })),
+            body: JSON.stringify(writeRequestBody({ content, concepts, domain }, author)),
         });
         // `stored` MUST BE A BOOLEAN before either verdict below may be printed.
         //
@@ -560,7 +634,7 @@ export function registerMemoryTools(server, deps) {
                 .min(CORE_LIMITS.readTopK.minimum)
                 .max(CORE_LIMITS.readTopK.maximum)
                 .optional()
-                .describe("Requested number of results (default: 5, what this server asks for when you omit it; the engine's own default of 10 never applies, because the field is always sent). ⚠️ Not a hard cap: association expansion can return MORE than this, and the relevance floor can return fewer — raising it does not reliably widen the result set. For a complete, exactly-bounded listing use memory_list_recent instead."),
+                .describe(`Requested number of results (default: 5, what ${serverNoun} asks for when you omit it; the engine's own default of 10 never applies, because the field is always sent). ⚠️ Not a hard cap: association expansion can return MORE than this, and the relevance floor can return fewer — raising it does not reliably widen the result set. For a complete, exactly-bounded listing use memory_list_recent instead.`),
             domain: z
                 .string()
                 .optional()
@@ -742,7 +816,15 @@ export function registerMemoryTools(server, deps) {
         // `structuredContent` carries every item, uncapped (OD-11): the cap
         // and its legend are TEXT-side concerns, and `structuredItem`
         // (src/render.ts) is deliberately not run through either.
-        return structured(withDomainEscapeLegend(capResult(text), ...items.map((it) => it?.domain)), { items: items.map(structuredItem) });
+        //
+        // Author names are candidates too, not just domains (I66-1..I66-3,
+        // issue #66): the text tag now quotes every author name through the
+        // same `exactLiteral` the `@domain` tag uses, so an escaped one needs
+        // the same "these are JSON string literals" legend an escaped domain
+        // already gets. `rawAuthorName` is the SAME raw value `formatAuthorTag`
+        // quoted, so this recomputation finds the same literal that is
+        // actually on the page.
+        return structured(withEscapeLegendAt(MAX_DOMAIN_TAG_LITERAL, capResult(text), ...items.map((it) => it?.domain), ...items.map((it) => rawAuthorName(it?.provenance))), { items: items.map(structuredItem) });
     });
     // --- Tool: memory_list_recent ---
     /**
@@ -1119,12 +1201,15 @@ export function registerMemoryTools(server, deps) {
         // The cursor is the last ACCEPTED batch's, never the newest one
         // seen: a batch that did not fit the budget was not returned, so
         // pointing past it would skip every entry in it.
-        withDomainEscapeLegend(capResult(formatRecentPage(items, acceptedCursor) +
+        //
+        // Author names are candidates too, not just domains: same reasoning
+        // as memory_read's call site above (I66-1..I66-3, issue #66).
+        withEscapeLegendAt(MAX_DOMAIN_TAG_LITERAL, capResult(formatRecentPage(items, acceptedCursor) +
             (stoppedEarly ? LIST_PAGE_EARLY_STOP_NOTE : ""), 
         // Still true, and now only reachable when ONE entry is larger
         // than the whole budget: the case `limit` cannot fix and the
         // global cap has to.
-        "Lower `limit` or add a `domain` for smaller pages."), ...items.map((it) => it?.domain)), {
+        "Lower `limit` or add a `domain` for smaller pages."), ...items.map((it) => it?.domain), ...items.map((it) => rawAuthorName(it?.provenance))), {
             items: items.map(structuredItem),
             // Same field name and meaning as the connector's `next_cursor`
             // (mnemoverse-mcp-remote `memoryListRecentOutput`): the cursor a
@@ -1204,7 +1289,7 @@ export function registerMemoryTools(server, deps) {
                 .array(z.string())
                 .min(1)
                 .optional()
-                .describe("Deprecated since 0.11, removed in 0.12: atom_ids is the old name of memory_ids, still accepted on its own until then. Pass memory_ids instead."),
+                .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."),
             outcome: z
                 .number()
                 .min(CORE_LIMITS.feedbackOutcome.minimum)
@@ -1249,7 +1334,7 @@ export function registerMemoryTools(server, deps) {
                 .int()
                 .nonnegative()
                 .optional()
-                .describe("Number of feedback-driven query/result concept co-activation edges changed by the service. This is separate from ordinary Hebbian strengthening among a memory's own concepts. This server does not send query_concepts, so live calls through this tool report 0; asynchronous acknowledgements also report 0."),
+                .describe(`Number of feedback-driven query/result concept co-activation edges changed by the service. This is separate from ordinary Hebbian strengthening among a memory's own concepts. ${serverNounCap} does not send query_concepts, so live calls through this tool report 0; asynchronous acknowledgements also report 0.`),
         },
         annotations: {
             title: "Rate Memory Helpfulness",
@@ -1483,9 +1568,9 @@ export function registerMemoryTools(server, deps) {
         // count, and the same rule: a value that is not a finite number is
         // unknown and prints nothing, never 0. Core's async mode acks with 0
         // before the worker runs (memory_engine.py `feedback` docstring), which
-        // is why this is the service's report too; production ran the sync path
-        // for every rating in the week checked (Axiom 2026-09-15..22:
-        // feedback_completed 630, feedback_completed_async 0).
+        // is why this is the service's report too; in production every rating
+        // observed so far took the synchronous path (the asynchronous
+        // acknowledgement is reachable but was not seen in the checked window).
         //
         // coactivation_edges is left out of the text on purpose: core links
         // concepts only when the request carries query_concepts, which this tool
@@ -1513,6 +1598,51 @@ export function registerMemoryTools(server, deps) {
     server.registerTool("memory_stats", {
         description: "Get an overview of the stored memory: total count, episodes vs consolidated prototypes, number of learned associations, the list of domains, and average quality scores. This memory is shared across all AI tools the user has connected to Mnemoverse. Use it to orient yourself, to confirm the exact domain name before writing to it, or when the user asks what you remember. Read-only — changes nothing.",
         inputSchema: {},
+        // `memory_count` and `domains` are copied from the connector's
+        // `memoryStatsOutput` (mnemoverse-mcp-remote, src/tools/index.ts), field
+        // for field and description for description, under the CONNECTOR's
+        // naming rather than core's (`total_atoms`): the same structured
+        // consumer can read both servers, and a data field spelled differently
+        // between them would defeat the point of one shared shape (decision Q3,
+        // owner, 2026-09-23). Both are required, matching the connector: a body
+        // without a usable value for either is not core's answer (see the guard
+        // in the handler below). The other five fields are this package's own
+        // addition, the rest of what this tool's own text already reports,
+        // each optional, present only when core sent a usable number for it.
+        outputSchema: {
+            memory_count: z
+                .number()
+                .int()
+                .nonnegative()
+                .describe("Number of saved memories."),
+            domains: z.array(z.string()).describe("User-defined memory domains."),
+            episodes: z
+                .number()
+                .int()
+                .nonnegative()
+                .optional()
+                .describe("Number of episodic (not yet consolidated) memories."),
+            prototypes: z
+                .number()
+                .int()
+                .nonnegative()
+                .optional()
+                .describe("Number of consolidated prototype memories."),
+            hebbian_edges: z
+                .number()
+                .int()
+                .nonnegative()
+                .optional()
+                .describe("Number of Hebbian concept-to-concept links, learned from concepts that occur together as memories are stored and used."),
+            avg_valence: z
+                .number()
+                .optional()
+                .describe("Average valence of stored memories: how well recalls turned out, on a scale from -1 to 1."),
+            avg_importance: z
+                .number()
+                .optional()
+                .describe("Average importance of stored memories, on a scale from 0 to 1."),
+        },
         annotations: {
             title: "Memory Statistics",
             readOnlyHint: true,
@@ -1522,6 +1652,28 @@ export function registerMemoryTools(server, deps) {
         },
     }, async () => {
         const r = await apiFetch("/memory/stats");
+        // REQUIRED-FIELD GUARD (OD-8 precedent, owner, 2026-09-23): `memory_count`
+        // and `domains` are REQUIRED in the outputSchema above, matching the
+        // connector's own `memoryStatsOutput`, so a body without a usable
+        // `total_atoms` (a non-negative safe integer) or without an ARRAY
+        // `domains` is not core's answer and there is no honest
+        // structuredContent to build for it. Before this schema existed, both
+        // degraded silently into this tool's own "unknown" numbers / "none
+        // reported" domains text; now they are `isError`, the same shape every
+        // other unreadable-answer reply in this file takes. isSafeInteger, not
+        // isInteger, for the same reason memory_feedback's count check gives:
+        // the schema is z.number().int(), and zod 4 rejects an integer above
+        // 2^53 - 1.
+        const totalAtomsRaw = r?.total_atoms;
+        const memoryCount = typeof totalAtomsRaw === "number" &&
+            Number.isSafeInteger(totalAtomsRaw) &&
+            totalAtomsRaw >= 0
+            ? totalAtomsRaw
+            : undefined;
+        const domainsRaw = r?.domains;
+        if (memoryCount === undefined || !Array.isArray(domainsRaw)) {
+            return unreadableAnswerReply("The stats answer", "the memory store's statistics", "the store is empty");
+        }
         // A field the server did not send is UNKNOWN, not zero. Rendering it as
         // "0" is the same class of lie as an empty search claiming emptiness:
         // "Associations: 0" reads as "this memory has learned nothing", which is
@@ -1570,29 +1722,71 @@ export function registerMemoryTools(server, deps) {
             "",
             "Counts cover your own domains. Shared rooms are separate stores and are not included — see memory_list_rooms.",
         ].join("\n");
-        return {
-            content: [
-                {
-                    type: "text",
-                    // Array.isArray, not `?? []`: `domains` is typed as a string[] but
-                    // arrives over the wire, and spreading a non-iterable object would
-                    // throw here — turning a malformed payload into a dead tool instead
-                    // of the "none reported" it degrades to two lines up.
-                    //
-                    // capResult is the second belt, not the mechanism: the domain list is
-                    // already bounded above, so this only fires if some future line grows
-                    // unboundedly. It stays because this was the ONE tool result with no
-                    // cap at all, and "every surface is capped" is worth being an
-                    // invariant rather than an argument about which surfaces can grow.
-                    // Its hint names a control this no-input tool actually has — none —
-                    // rather than the read tool's "use a more specific query".
-                    //
-                    // Legend AFTER the cap, as everywhere else: it must describe the names
-                    // that SURVIVED, and it is appended at the end, where the cap cuts.
-                    text: withDomainEscapeLegend(capResult(text, "The domain list was truncated — some domain names are not shown."), ...(Array.isArray(r?.domains) ? r.domains : [])),
-                },
-            ],
-        };
+        // STRUCTURED TWIN of the optional numeric fields, following the same
+        // rule memory_feedback's does: a value core did not send, or sent in a
+        // shape the schema could not hold, is absent from structuredContent,
+        // never defaulted to 0. Int fields use isSafeInteger for the reason the
+        // guard above gives (the schema is z.number().int(), and zod 4 rejects
+        // an integer above 2^53 - 1); the two averages use isFinite, so an
+        // Infinity smuggled through a raw body (e.g. avg_valence: 1e400) never
+        // reaches a structured consumer as data. The TEXT above keeps printing
+        // 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 finiteOrUndefined = (v) => typeof v === "number" && Number.isFinite(v) ? v : undefined;
+        const episodesStructured = safeIntOrUndefined(r?.episodes);
+        const prototypesStructured = safeIntOrUndefined(r?.prototypes);
+        const hebbianEdgesStructured = safeIntOrUndefined(r?.hebbian_edges);
+        const avgValenceStructured = finiteOrUndefined(r?.avg_valence);
+        const avgImportanceStructured = finiteOrUndefined(r?.avg_importance);
+        // DOMAINS FOR structuredContent: FILTERED, not an error and not zeroed
+        // (decisions S7-1/S7-2, owner, 2026-09-23). A non-string element is
+        // dropped rather than turning the whole reply into isError, and the
+        // TEXT above already counts it in formatDomainList's "not shown, cannot
+        // be printed exactly" clause, so the count is not silently lost, only
+        // moved off the surface a structured consumer reads. What a structured
+        // consumer would silently lose is the fact that anything was dropped at
+        // all, so the drop is also reported once on stderr, in this package's
+        // existing startup-diagnostic style ("Mnemoverse: ..." in src/index.ts),
+        // the operator's channel rather than the model's: putting this in the
+        // tool text would surface an implementation detail to the agent reading it.
+        const domainsStructured = domainsRaw.filter((d) => typeof d === "string");
+        const droppedDomains = domainsRaw.length - domainsStructured.length;
+        if (droppedDomains > 0) {
+            console.error(`Mnemoverse: memory_stats dropped ${droppedDomains} non-string domain ` +
+                `entr${droppedDomains === 1 ? "y" : "ies"} from structuredContent.domains ` +
+                `(still counted in the text's "not shown" total).`);
+        }
+        return structured(
+        // Array.isArray, not `?? []`: `domains` is typed as a string[] but
+        // arrives over the wire, and spreading a non-iterable object would
+        // throw here — turning a malformed payload into a dead tool instead
+        // of the "none reported" it degrades to two lines up.
+        //
+        // capResult is the second belt, not the mechanism: the domain list is
+        // already bounded above, so this only fires if some future line grows
+        // unboundedly. It stays because this was the ONE tool result with no
+        // cap at all, and "every surface is capped" is worth being an
+        // invariant rather than an argument about which surfaces can grow.
+        // Its hint names a control this no-input tool actually has — none —
+        // rather than the read tool's "use a more specific query".
+        //
+        // Legend AFTER the cap, as everywhere else: it must describe the names
+        // that SURVIVED, and it is appended at the end, where the cap cuts.
+        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 }),
+            ...(hebbianEdgesStructured === undefined
+                ? {}
+                : { hebbian_edges: hebbianEdgesStructured }),
+            ...(avgValenceStructured === undefined ? {} : { avg_valence: avgValenceStructured }),
+            ...(avgImportanceStructured === undefined
+                ? {}
+                : { avg_importance: avgImportanceStructured }),
+        });
     });
     // --- Tool: memory_create_room ---
     //
@@ -1605,6 +1799,32 @@ export function registerMemoryTools(server, deps) {
     // carries the owner-chosen room name raw, which this file prints only
     // through roomNamePhrase (CN-032). The usage lines below say the same
     // things in MCP terms, scope-gated on join.
+    // OUTPUT SCHEMAS for the three room tools (S8, structured-output plan):
+    // `room_id`/`address`/`room_address`/`scope` copied from the connector's
+    // `roomCreatedOutput`/`roomInviteOutput`/`roomJoinedOutput`
+    // (mnemoverse-mcp-remote, src/tools/index.ts), field for field and
+    // description for description.
+    //
+    // OD-13 (owner, 2026-09-23): several fields the connector marks required
+    // are OPTIONAL here: `name` on create and join, `scope`/`already_member`
+    // on join, and `code`/`scope`/`room_address`/`expires_at` on invite. The
+    // connector's own core client types those fields as always-present; this
+    // package treats every wire value as untyped (the general rule this whole
+    // file follows) and already has a non-degraded THREE-state phrase for a
+    // room name core did not send (`roomNamePhrase`) and for a join whose
+    // scope core did not report (`roomScopeVerdict`'s "unspecified" arm), so
+    // "core sent no usable value for this field" is an existing, honestly
+    // representable outcome here, not an error, and the schema says so by
+    // making the field optional rather than forcing a fabricated placeholder
+    // into a field declared required.
+    //
+    // `join_url`/`share_message` on invite stay as today: at least one of the
+    // two must be usable or the call is `isError` (unchanged from before this
+    // schema existed), so `share_message` is the one guaranteed field, built
+    // from the SAME fallback the text already prints (share_message when core
+    // sent one, else join_url), and `join_url` itself is optional, present
+    // only when core actually returned a string for it.
+    // --- Tool: memory_create_room ---
     server.registerTool("memory_create_room", {
         description: "Create a SHARED memory room — a space OTHER people's assistants can read, and write too when their invite granted read_write (the default scope), across Claude/ChatGPT/Cursor. Use when the user wants to share context or collaborate with someone else (e.g. 'make a room for me and Olya'). Returns the room's address; pass that address as the `domain` on memory_write/memory_read to use it, and on memory_list_recent to catch up on what others added. To bring someone in, call memory_invite_to_room next.",
         inputSchema: {
@@ -1619,6 +1839,15 @@ export function registerMemoryTools(server, deps) {
                 .optional()
                 .describe("Optional description of the room."),
         },
+        outputSchema: {
+            room_id: z
+                .string()
+                .describe("The room's id (room_...); pass to memory_invite_to_room."),
+            address: z
+                .string()
+                .describe("Domain address (xroom:<id>); pass as `domain` on read/write."),
+            name: z.string().optional().describe("The room name as stored."),
+        },
         annotations: {
             title: "Create shared room",
             readOnlyHint: false,
@@ -1641,7 +1870,13 @@ export function registerMemoryTools(server, deps) {
         const roomId = safeInline(r?.room_id);
         // If core returned no usable id (empty body / sanitized away), don't print
         // broken `domain=""` guidance — say so instead (Copilot).
-        const text = address
+        //
+        // GATE (S8-1, owner, 2026-09-23): core's RoomCreatedSchema sends
+        // room_id alongside address on every create, so `roomId` now joins
+        // `address` in the condition that picks this branch: a body missing
+        // a usable one of either is not core's answer, the same class of
+        // unreadable 2xx this file already refuses rather than describes.
+        const text = address && roomId
             ? `Created shared room ${roomName}. Address: ${address}\n` +
                 `Use it now: pass domain="${address}" on memory_write / memory_read, and on memory_list_recent to catch up on what others added.\n` +
                 (roomId
@@ -1649,18 +1884,35 @@ export function registerMemoryTools(server, deps) {
                     : "")
             : `Room ${roomName} was created but the server did not return a usable address — ` +
                 `retry, or check that your API key is set.`;
-        return {
-            content: [
-                {
-                    type: "text",
-                    // Legend AFTER the cap (same rule as memory_read/memory_list_recent):
-                    // capResult cuts from the end, so a legend applied first would be the
-                    // first casualty; applied to the capped text it also drops itself when
-                    // the cap removed the only escaped name.
-                    text: withDomainEscapeLegend(capResult(text), rawName),
-                },
-            ],
-        };
+        // Legend AFTER the cap (same rule as memory_read/memory_list_recent):
+        // capResult cuts from the end, so a legend applied first would be the
+        // first casualty; applied to the capped text it also drops itself when
+        // the cap removed the only escaped name.
+        const finalText = withDomainEscapeLegend(capResult(text), rawName);
+        // Same gate as the text above: no usable address or no usable room_id
+        // is not core's answer, and there is no honest structuredContent for
+        // it either. The existing degrade sentence is the whole reply now,
+        // with isError: true, instead of a 200-shaped "success" with nothing
+        // a caller can act on.
+        if (!address || !roomId) {
+            return {
+                content: [{ type: "text", text: finalText }],
+                isError: true,
+            };
+        }
+        // STRUCTURED `name` comes from the RESPONSE only, never from the
+        // request's `name` the text above falls back to: the schema says "as
+        // stored", and a body that omits `name` gives this client no evidence
+        // of what core stored, so the key is absent rather than an echo of the
+        // caller's own spelling dressed up as core's answer (Copilot, review
+        // round 2). The text keeps its fallback: it is written for the caller
+        // who chose the name and stays byte-identical.
+        const nameStructured = structuredText(r?.name, 200);
+        return structured(finalText, {
+            room_id: roomId,
+            address,
+            ...(nameStructured === undefined ? {} : { name: nameStructured }),
+        });
     });
     // --- Tool: memory_invite_to_room ---
     server.registerTool("memory_invite_to_room", {
@@ -1694,6 +1946,20 @@ export function registerMemoryTools(server, deps) {
                 .optional()
                 .describe("How many people may join with this invite (default 1, single-use)."),
         },
+        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."),
+            code: z
+                .string()
+                .optional()
+                .describe("The invite code (mnvr_...). Single-use by default, with a configurable use limit. Shown once."),
+            scope: z.string().optional().describe("Role the invitee will get."),
+            room_address: z
+                .string()
+                .optional()
+                .describe("The room's domain address (xroom:<id>)."),
+            expires_at: z.string().nullable().optional().describe("ISO 8601 expiry, or null."),
+        },
         annotations: {
             title: "Invite to room",
             readOnlyHint: false,
@@ -1708,18 +1974,62 @@ export function registerMemoryTools(server, deps) {
             method: "POST",
             body: JSON.stringify({ scope, expires_in_days, max_uses }),
         });
-        return {
-            content: [
-                {
-                    type: "text",
-                    // Shown to the room OWNER (who minted it), not a foreign principal, so
-                    // the core-generated share_message is fine as-is; capResult only bounds
-                    // its length for the Connectors-Directory 25K cap.
-                    text: capResult(`Invite ready. Forward this message to the person you're inviting:\n\n` +
-                        `${r?.share_message ?? r?.join_url ?? "(no message returned)"}`),
-                },
-            ],
-        };
+        // ONE selection feeds both surfaces (Copilot, review round 2): the
+        // message the text forwards is core's share_message when the body has
+        // one (its raw value, exactly as before this schema existed), else
+        // join_url, else the "(no message returned)" sentence.
+        const rawMessage = r?.share_message ?? r?.join_url;
+        const text = capResult(`Invite ready. Forward this message to the person you're inviting:\n\n` +
+            `${rawMessage ?? "(no message returned)"}`);
+        // Shown to the room OWNER (who minted it), not a foreign principal, so
+        // the core-generated share_message is fine as-is; capResult only bounds
+        // its length for the Connectors-Directory 25K cap. STRUCTURED
+        // `share_message` (S8-4, owner, 2026-09-23) is that SAME selected
+        // value, normalised through structuredText, so the data never carries
+        // a message the text did not show. A selected value that normalises to
+        // nothing (no share_message and no join_url, or a share_message that is
+        // empty, whitespace-only or not a string at all) is not this tool's
+        // success case any more: the text above is unchanged (the blank or the
+        // "(no message returned)" sentence, as before) and the reply is
+        // isError: true, since there is no honest
+        // structuredContent.share_message to pair it with.
+        const shareMessageStructured = structuredText(rawMessage, 800);
+        if (shareMessageStructured === undefined) {
+            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):
+        // core builds it as `<base>/<code>`, which safeInline's character class
+        // carries unchanged; anything else it would have to alter is not a URL
+        // this client should hand on as one. Absent when nothing remains.
+        const joinUrlSafe = safeInline(r?.join_url, 400);
+        const joinUrlStructured = joinUrlSafe === "" ? undefined : joinUrlSafe;
+        // The other machine fields the same way: safeInline returns "" for a
+        // non-string, an empty string and a string with nothing it may keep,
+        // and "" is not a usable code, scope or address, so the key is absent
+        // (CodeRabbit, review round 2). Present only when something remains.
+        const codeSafe = safeInline(r?.code);
+        const codeStructured = codeSafe === "" ? undefined : codeSafe;
+        const scopeSafe = safeInline(r?.scope);
+        const scopeStructured = scopeSafe === "" ? undefined : scopeSafe;
+        const roomAddressSafe = safeInline(r?.room_address);
+        const roomAddressStructured = roomAddressSafe === "" ? undefined : roomAddressSafe;
+        // `expires_at` through utcInstant's RETURN, the rule memory_read's
+        // `created_at` already follows (S4): a value that states its offset is
+        // carried exactly as sent, an offset-less one, which this package reads
+        // as UTC by contract, is re-emitted as the UTC ISO-8601 instant, so a
+        // 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);
+        return structured(text, {
+            share_message: shareMessageStructured,
+            ...(joinUrlStructured === undefined ? {} : { join_url: joinUrlStructured }),
+            ...(codeStructured === undefined ? {} : { code: codeStructured }),
+            ...(scopeStructured === undefined ? {} : { scope: scopeStructured }),
+            ...(roomAddressStructured === undefined ? {} : { room_address: roomAddressStructured }),
+            ...(expiresAtStructured === undefined ? {} : { expires_at: expiresAtStructured }),
+        });
     });
     // --- Tool: memory_join_room ---
     server.registerTool("memory_join_room", {
@@ -1727,6 +2037,19 @@ export function registerMemoryTools(server, deps) {
         inputSchema: {
             code: z.string().min(1).max(200).describe("The invite code (mnvr_...)."),
         },
+        outputSchema: {
+            room_id: z.string().describe("The room's id (room_...)."),
+            address: z
+                .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')."),
+            already_member: z
+                .boolean()
+                .optional()
+                .describe("True if you were already a member (no-op join)."),
+            next_steps: z.string().describe("How to use the room now."),
+        },
         annotations: {
             title: "Join room",
             readOnlyHint: false,
@@ -1748,6 +2071,7 @@ export function registerMemoryTools(server, deps) {
         const roomName = roomNamePhrase(r?.name);
         const scope = safeInline(r?.scope) || "member";
         const address = safeInline(r?.address);
+        const roomId = safeInline(r?.room_id);
         const prefix = r?.already_member
             ? `You're already a member of ${roomName}.`
             : `Joined ${roomName} (${scope}).`;
@@ -1756,28 +2080,102 @@ export function registerMemoryTools(server, deps) {
         // isRoomDomain): a "read" invite gets told memory_write will be refused
         // rather than offered it, and a scope the response did not report at all
         // gets no promise about write either way.
+        //
+        // GATE (S8-2, mirrors create's S8-1, owner, 2026-09-23): core's
+        // JoinedRoomSchema sends room_id alongside address on every join, so
+        // `roomId` now joins `address` in the condition that picks this
+        // sentence: same wording as before (it still names only "address" -
+        // the caller cannot tell which of the two core actually omitted, and a
+        // second sentence for a case indistinguishable from this one would be
+        // a distinction this client cannot see either).
         const verdict = roomScopeVerdict(r?.scope);
-        const usage = !address
+        const usage = !address || !roomId
             ? `The server did not return a room address — retry, or check that your API key is set.`
             : verdict === "read_write"
                 ? `Use it: pass domain="${address}" on memory_write / memory_read to read and write the shared room, and on memory_list_recent to catch up on what is new.`
                 : verdict === "read"
                     ? `Use it: pass domain="${address}" on memory_read or memory_list_recent to read it; this membership is read-only, so memory_write to that address will be refused.`
                     : `Use it: pass domain="${address}" on memory_read or memory_list_recent to read it — the server did not report this membership's write access, so whether memory_write to that address would succeed is unknown.`;
-        return {
-            content: [
-                {
-                    type: "text",
-                    // Legend after the cap — same ordering rule as everywhere else.
-                    text: withDomainEscapeLegend(capResult(`${prefix}\n${usage}`), r?.name),
-                },
-            ],
-        };
+        // No usable address or room_id: the reply is the same text as before
+        // this schema existed (the prefix line plus the degrade sentence), now
+        // isError: true, since there is no honest structuredContent for a join
+        // whose room this client cannot address. The text stays byte-identical
+        // on purpose: whether this reply should stop saying "Joined" is a
+        // wording decision for the owner, not for this slice.
+        if (!address || !roomId) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: withDomainEscapeLegend(capResult(`${prefix}\n${usage}`), r?.name),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const nameStructured = structuredText(r?.name, 200);
+        // STRUCTURED `next_steps` (S8-6, owner, 2026-09-23) is this SAME usage
+        // sentence, never core's own `next_steps`: that field points at REST
+        // endpoints and is deliberately not echoed (see the comment above
+        // memory_create_room). `?? usage` is a defensive fallback for the
+        // unreachable case where structuredText would normalise `usage` to
+        // nothing; it is built from safe, already-sanitised parts and never
+        // actually empties.
+        const nextStepsStructured = structuredText(usage, 500) ?? usage;
+        // `scope` absent when safeInline leaves nothing, as on invite.
+        const scopeSafe = safeInline(r?.scope);
+        const scopeStructured = scopeSafe === "" ? undefined : scopeSafe;
+        return structured(
+        // Legend after the cap, same ordering rule as everywhere else.
+        withDomainEscapeLegend(capResult(`${prefix}\n${usage}`), r?.name), {
+            room_id: roomId,
+            address,
+            ...(nameStructured === undefined ? {} : { name: nameStructured }),
+            ...(scopeStructured === undefined ? {} : { scope: scopeStructured }),
+            ...(typeof r?.already_member === "boolean"
+                ? { already_member: r.already_member }
+                : {}),
+            next_steps: nextStepsStructured,
+        });
     });
     // --- Tool: memory_list_rooms ---
+    // OUTPUT SCHEMA (S9, structured-output plan): `room_id`/`name`/`address`/
+    // `role`/`scope`/`archived` copied from the connector's `roomListOutput`
+    // (mnemoverse-mcp-remote, src/tools/index.ts), field for field and
+    // description for description.
+    //
+    // OD-14 (owner, 2026-09-23, S9-1): `name` is OPTIONAL here though the
+    // connector's own schema marks it a REQUIRED z.string(); so is `scope`, for
+    // the reason OD-13 gave on memory_join_room: the text already has a
+    // supported, non-degraded state for a membership whose write access core
+    // did not report ("this membership's write access was not reported"), and
+    // a required field would turn that state into an SDK "Output validation
+    // error" (review round 2). `structuredText`
+    // (src/names.ts) returns undefined for a genuinely empty or absent name, a
+    // real, already-tested case ("keeps '(unnamed room)' for a genuinely absent
+    // or empty name", test/handlers.test.ts), and forcing that through a
+    // REQUIRED field would make the SDK reject the WHOLE reply with "Output
+    // validation error" on an unnamed room, which is a supported, non-error
+    // outcome, not a malformed response. The alternative, falling back to the
+    // literal empty string, was rejected: the text would keep saying
+    // "(unnamed room)" while the data silently said `name: ""`, the same
+    // text/data lie the anti-fabrication rule this package already applies to
+    // every other optional field exists to prevent.
     server.registerTool("memory_list_rooms", {
         description: "List the shared memory rooms you can use — the ones you OWN plus the ones you've JOINED — each with the address to pass as `domain` on memory_read, and on memory_write too where your membership scope is read_write; a read-only membership has that write refused. Use this to RE-FIND a room in a new session (e.g. 'what rooms do I have?', 'resume the room with Olya') instead of having to create or re-join it.",
         inputSchema: {},
+        outputSchema: {
+            rooms: z.array(z.object({
+                room_id: z.string().describe("The room's id (room_...)."),
+                name: z.string().optional().describe("The room name."),
+                address: z
+                    .string()
+                    .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)."),
+            })),
+        },
         annotations: {
             title: "List rooms",
             readOnlyHint: true,
@@ -1800,15 +2198,8 @@ export function registerMemoryTools(server, deps) {
             return unreadableAnswerReply("The room list", "a list of your rooms", "you have none");
         }
         if (rooms.state === "none") {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: "You have no shared rooms yet. Create one with memory_create_room, " +
-                            "or join one with memory_join_room using an invite code.",
-                    },
-                ],
-            };
+            return structured("You have no shared rooms yet. Create one with memory_create_room, " +
+                "or join one with memory_join_room using an invite code.", { rooms: [] });
         }
         // ARCHIVED ROOMS ARE LISTED HERE, unlike in the scope note — this tool's job
         // is the inventory, and the `[archived]` tag says which ones cannot be read.
@@ -1851,22 +2242,136 @@ export function registerMemoryTools(server, deps) {
             return `- ${name} (${role}${scope ? `, ${scope}` : ""})${tail}`;
         });
         const text = `Your shared rooms (${list.length}):\n${lines.join("\n")}`;
-        return {
-            content: [
-                {
-                    type: "text",
-                    // Legend after the cap: this is the one room surface long enough to
-                    // actually overflow, and the legend must describe the names that
-                    // SURVIVED the cut, not the ones it removed.
-                    text: withDomainEscapeLegend(capResult(text, "The room list was truncated — some rooms are not shown."), ...list.map((r) => r?.name)),
-                },
-            ],
-        };
+        // Legend after the cap: this is the one room surface long enough to
+        // actually overflow, and the legend must describe the names that
+        // SURVIVED the cut, not the ones it removed.
+        const finalText = withDomainEscapeLegend(capResult(text, "The room list was truncated — some rooms are not shown."), ...list.map((r) => r?.name));
+        // STRUCTURED rows (S9-1/S9-3, owner, 2026-09-23): room_id/address/role/
+        // scope through the SAME safeInline sanitiser the text loop above
+        // already applies (address keeps the identical xroom:<room_id>
+        // fallback), archived through Boolean(). The name is withheld from the
+        // data in exactly the cases the text withholds it: roomNamePhrase
+        // prints "(room name cannot be printed exactly)" when exactLiteral
+        // refuses the JSON literal (longer than MAX_DOMAIN_LITERAL once quoted
+        // and escaped), so the same exactLiteral check decides whether `name`
+        // is present here, and the value carried is the structuredText
+        // normalisation of the raw name (control, bidi and zero-width
+        // characters out), never a truncated prefix presented as the name
+        // (review round 2: the two caps measure different things, a JSON
+        // literal and a code-point count, so reusing the number alone did not
+        // make the surfaces agree). Absent, never fabricated as "" or
+        // "(unnamed room)", for a room with no usable name (OD-14 above).
+        // One stated exception (review round 3): a name made only of the
+        // characters structuredText removes (whitespace, control, bidi,
+        // zero-width) is printed exactly in the text, as an escaped literal
+        // with the legend, but leaves nothing to carry as a plain data value;
+        // the data omits the key rather than carry "" (which would claim the
+        // name is empty) or the raw characters (which the data surface keeps
+        // out by rule). The same exception holds for every structuredText
+        // field on this surface.
+        //
+        // Core's RoomListItemSchema sends room_id, address and role on every
+        // row; a row whose room_id or role sanitises to nothing (or whose
+        // address cannot even be rebuilt from room_id) is not core's row and
+        // is dropped from the data rather than emitted with fabricated empty
+        // strings in required fields (review round 2). `scope` is optional
+        // (OD-14 above): absent from the data when the text says the write
+        // access was not reported. The text keeps its existing per-row
+        // degrade; the drop is counted and reported once on stderr, as
+        // vault_list and memory_stats report theirs.
+        const roomsStructured = [];
+        let droppedRooms = 0;
+        for (const r of list) {
+            const roomId = safeInline(r?.room_id);
+            const address = safeInline(r?.address) || (roomId ? `xroom:${roomId}` : "");
+            const role = safeInline(r?.role);
+            const scope = safeInline(r?.scope);
+            if (!roomId || !address || !role) {
+                droppedRooms += 1;
+                continue;
+            }
+            const nameStructured = typeof r?.name === "string" && exactLiteral(r.name, MAX_DOMAIN_LITERAL)
+                ? structuredText(r.name, MAX_DOMAIN_LITERAL)
+                : undefined;
+            roomsStructured.push({
+                room_id: roomId,
+                address,
+                role,
+                ...(scope ? { scope } : {}),
+                archived: Boolean(r?.archived),
+                ...(nameStructured === undefined ? {} : { name: nameStructured }),
+            });
+        }
+        if (droppedRooms > 0) {
+            console.error(`Mnemoverse: memory_list_rooms dropped ${droppedRooms} malformed room ` +
+                `row${droppedRooms === 1 ? "" : "s"} from structuredContent.rooms ` +
+                `(room_id, address or role missing or not usable; still shown in the text).`);
+        }
+        return structured(finalText, { rooms: roomsStructured });
     });
     // --- Tool: vault_list ---
+    // Core's CreateSecretRequest caps (mnemoverse-core src/mnemo/api/vault_routes.py):
+    // alias max_length 200, context max_length 10,000. Concepts carry no cap
+    // of their own there; 200 is the alias cap reused for a tag, not a new
+    // number. Not in src/limits.ts because the generator covers the memory
+    // routes, not the vault ones.
+    const VAULT_ALIAS_CAP = 200;
+    const VAULT_CONTEXT_CAP = 10_000;
+    const VAULT_CONCEPT_CAP = 200;
+    // OUTPUT SCHEMA (S9, structured-output plan): `alias`/`context`/`concepts`
+    // copied from the connector's `vaultListOutput` (mnemoverse-mcp-remote,
+    // src/tools/index.ts), field for field and description for description,
+    // all three REQUIRED, matching the connector exactly (unlike
+    // memory_list_rooms's `name`, above).
+    //
+    // OD-15 (owner, 2026-09-23, S9-2): a row whose `alias` or `context` is not
+    // a usable string is SKIPPED from `secrets` in structuredContent rather
+    // than turning the whole call into `isError`. The plan's original wording
+    // (isError on one bad row) directly reversed an existing, deliberately
+    // named test, "a broken alias is one anonymous row, not a dead tool"
+    // (test/handlers.test.ts), which the owner confirmed keeping as-is: the
+    // text already substitutes "(no alias)" for that ONE row and leaves every
+    // other row and the call itself untouched, so the data follows the same
+    // rule this package applies everywhere else, a value the text withholds
+    // must be withheld from the data too. Because both fields are REQUIRED
+    // here, exactly as in the connector, there is no honest partial row to
+    // emit for one that fails either check, including a row whose `context`
+    // (or `alias`) was never sent at all (`typeof undefined` is not
+    // `"string"`): this package does not fabricate `""` for a value it does
+    // not have, the same rule OD-14 above applies to a room name. The skip is
+    // reported once per call on stderr, in this package's existing
+    // startup-diagnostic style (src/index.ts's "Mnemoverse: ..." lines,
+    // mirroring memory_stats's S7 domain-drop diagnostic), because a
+    // structured consumer reading only `structuredContent.secrets` has no
+    // other way to learn the array is shorter than the count in the text's own
+    // header line.
+    //
+    // `concepts` is a brand-new field with no text-side precedent, nothing in
+    // this tool's text renders it. Core's SecretSummary sends it on every row,
+    // so a row without it, or with a value that is not an array of strings,
+    // is treated the same as a malformed alias/context and drops the row: no
+    // `[]` is fabricated for a value core did not send, and there is no honest
+    // subset of an unshaped value to keep.
+    //
+    // Free text on this surface (alias, context, each concept) goes through
+    // structuredText with core's own caps (alias 200, context 10,000, a
+    // concept 200; vault_routes.py CreateSecretRequest), the same normalisation
+    // the room name gets: a value that normalises to nothing (empty,
+    // whitespace-only, control characters only) is not usable, and the row is
+    // dropped rather than carried as "" (review round 2). The text prints its
+    // own safeInline reading of alias and context unchanged.
     server.registerTool("vault_list", {
-        description: "List the secrets stored in your Mnemoverse Vault — by ALIAS and purpose only; the secret VALUE is never returned or shown to you, and no tool on this server returns it. Use this to check WHICH secrets the user has stored and under what alias (e.g. the user says 'do I have a GitHub token saved?'). Only YOUR account's secrets are listed.",
+        description: `List the secrets stored in your Mnemoverse Vault — by ALIAS and purpose only; the secret VALUE is never returned or shown to you, and no tool on ${serverNoun} returns it. Use this to check WHICH secrets the user has stored and under what alias (e.g. the user says 'do I have a GitHub token saved?'). Only YOUR account's secrets are listed.`,
         inputSchema: {},
+        outputSchema: {
+            secrets: z.array(z.object({
+                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."),
+                concepts: z.array(z.string()).describe("Concept tags."),
+            })),
+        },
         annotations: {
             title: "List vault secrets",
             readOnlyHint: true,
@@ -1886,14 +2391,7 @@ export function registerMemoryTools(server, deps) {
             return unreadableAnswerReply("The secret list", "a list of your Vault secrets", "none are stored");
         }
         if (list.length === 0) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: "No secrets are stored in your Vault yet.",
-                    },
-                ],
-            };
+            return structured("No secrets are stored in your Vault yet.", { secrets: [] });
         }
         const lines = list.map((s) => {
             const alias = safeInline(s?.alias) || "(no alias)";
@@ -1902,14 +2400,38 @@ export function registerMemoryTools(server, deps) {
         });
         const text = `Your Vault secrets (${list.length}) — alias and purpose only, never the value:\n` +
             lines.join("\n");
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: capResult(text, "The secret list was truncated — some secrets are not shown."),
-                },
-            ],
-        };
+        const finalText = capResult(text, "The secret list was truncated — some secrets are not shown.");
+        // STRUCTURED rows (S9-2, owner, 2026-09-23; see the OD-15 comment
+        // above): core's SecretSummary sends alias, context and concepts on
+        // every row, so a row is kept only when alias and context are strings
+        // and concepts is an array of strings; a row missing any of the three,
+        // or carrying one in another shape, is not core's row and is dropped
+        // from the data, never defaulted (no "" for a context, no [] for
+        // concepts). The call itself stands; the drop is counted and reported
+        // once on stderr.
+        const secretsStructured = [];
+        let droppedSecrets = 0;
+        for (const s of list) {
+            const alias = structuredText(s?.alias, VAULT_ALIAS_CAP);
+            const context = structuredText(s?.context, VAULT_CONTEXT_CAP);
+            const conceptsRaw = s?.concepts;
+            const concepts = Array.isArray(conceptsRaw)
+                ? conceptsRaw.map((c) => structuredText(c, VAULT_CONCEPT_CAP))
+                : 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 });
+        }
+        if (droppedSecrets > 0) {
+            console.error(`Mnemoverse: vault_list dropped ${droppedSecrets} malformed secret ` +
+                `row${droppedSecrets === 1 ? "" : "s"} from structuredContent.secrets ` +
+                `(alias, context or concepts missing, empty or not in core's shape; ` +
+                `still shown in the text).`);
+        }
+        return structured(finalText, { secrets: secretsStructured });
     });
 }
 //# sourceMappingURL=tools.js.map