@mnemoverse/mcp-memory-server 0.10.2 → 0.12.0

package/dist/resources.js

@@ -0,0 +1,97 @@
+/**
+ * MCP resource: one saved memory by id, as `memory://item/{memory_id}`.
+ *
+ * Clients that support resources (Claude.ai connectors attach them through an
+ * @-mention) can pull one specific memory into context. The ids are the `id:`
+ * lines of memory_read and memory_list_recent results, so this is the "open
+ * this memory" companion to the recall tools. There is no listing: the
+ * template is advertised, and reading needs a known id.
+ *
+ * Moved here from the hosted connector (mnemoverse-mcp-remote,
+ * src/resources/index.ts) in step 3c of the ADR-025 plan, with the same URI
+ * template, name and output, so the connector can register this instead of
+ * its copy. It returns only `memory_id`, `content` and `domain`: the engine's
+ * point read also carries importance, valence, access counts and metadata,
+ * which a model opening a memory does not need.
+ *
+ * Two limits, both the engine's. The point read looks only in the caller's
+ * own store (GET /memory/atoms/{id} takes no domain), so a memory read from a
+ * shared room cannot be opened here; the description says so. And a Vault
+ * secret is safe to open: its value lives in a column no read returns.
+ */
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
+import { ApiError } from "./errors.js";
+import { unreadableAnswerText, wordedApiFetch } from "./tools.js";
+/** MCP's code for a resource that does not exist (spec, "Resources: Error Handling"). */
+const RESOURCE_NOT_FOUND = -32002;
+/**
+ * The URI segment as the template hands it over is still percent-encoded.
+ * Decode it once, so the request path encodes the id itself rather than its
+ * encoding; a malformed escape is kept as sent (and then encoded, so it can
+ * never become a path separator).
+ */
+function decodeOnce(segment) {
+    try {
+        return decodeURIComponent(segment);
+    }
+    catch {
+        return segment;
+    }
+}
+/**
+ * Register the `memory://item/{memory_id}` resource on `server`. It reaches the
+ * API only through `deps.apiFetch`, like the tools.
+ */
+export function registerMemoryResources(server, deps) {
+    // The same `wording` treatment as registerMemoryTools (STEP4-2): a
+    // resource read that fails is explained in this registration's own voice.
+    const { wording } = deps;
+    const apiFetch = wording === undefined ? deps.apiFetch : wordedApiFetch(deps.apiFetch, wording);
+    server.registerResource("memory-item", new ResourceTemplate("memory://item/{memory_id}", { list: undefined }), {
+        title: "Saved memory",
+        description: "Read one saved memory by its memory ID. IDs come from memory_read results. Opens memories in your own store; a memory read from a shared room cannot be opened by ID.",
+        mimeType: "application/json",
+    }, async (uri, variables) => {
+        const id = decodeOnce(String(variables.memory_id));
+        let answer;
+        try {
+            answer = await apiFetch(`/memory/atoms/${encodeURIComponent(id)}`);
+        }
+        catch (err) {
+            // The message is the package's own explanation of the failure
+            // (src/errors.ts), so a 429 keeps the engine's quota sentence and a
+            // 404 says what was not found. A 404 also gets MCP's resource-not-found
+            // code, so a client can tell "no such memory" from a failure.
+            const message = err instanceof Error ? err.message : String(err);
+            const code = err instanceof ApiError && err.status === 404 ? RESOURCE_NOT_FOUND : ErrorCode.InternalError;
+            throw new McpError(code, message);
+        }
+        // A success whose body is not a memory (an empty 204, which apiFetch
+        // returns as {}, or any other shape) is not passed off as one: without
+        // this check it became {"memory_id": "<the id asked for>"}, a resource
+        // made up from the request (Copilot on #149). Content and domain must be
+        // strings, as the engine's AtomDetailSchema requires.
+        const atom = answer;
+        if (typeof atom !== "object" ||
+            atom === null ||
+            typeof atom.content !== "string" ||
+            typeof atom.domain !== "string") {
+            throw new McpError(ErrorCode.InternalError, unreadableAnswerText("The memory", "the memory", "it is empty or gone"));
+        }
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: "application/json",
+                    text: JSON.stringify({
+                        memory_id: typeof atom.id === "string" ? atom.id : id,
+                        content: atom.content,
+                        domain: atom.domain,
+                    }),
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=resources.js.map

package/dist/resources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.js","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"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"}

package/dist/shared.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `@mnemoverse/mcp-memory-server/shared`: the MCP surface, for any server.
+ *
+ * ADR-025 (mnemoverse-core): this package defines the Mnemoverse MCP surface,
+ * and a server that exposes Mnemoverse memory over MCP registers these tools
+ * instead of keeping its own copy. Importing this entry point starts nothing:
+ * the stdio server lives in the package's main entry, which this file does not
+ * import.
+ *
+ *     import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+ *     import {
+ *       registerMemoryPrompts,
+ *       registerMemoryResources,
+ *       registerMemoryTools,
+ *       SERVER_INSTRUCTIONS,
+ *     } from "@mnemoverse/mcp-memory-server/shared";
+ *
+ *     const server = new McpServer({ name, version }, { instructions: SERVER_INSTRUCTIONS });
+ *     registerMemoryTools(server, { apiFetch });
+ *     registerMemoryPrompts(server);
+ *     registerMemoryResources(server, { apiFetch });
+ *
+ * `apiFetch` is the server's own way to reach the API (credential, base URL,
+ * transport). Its contract is on the `ApiFetch` type: reject with `ApiError`,
+ * `NetworkError` or `UnreadableBodyError`, because the tools branch on which.
+ *
+ * `MAX_RESULT_CHARS` and `capResult` are the tool-result size cap and the
+ * helper that applies it: 96,000 characters (24,000 tokens), the one bound
+ * both servers use for a tool result's text (`structuredContent` is not
+ * capped, OD-11). ADR-025 makes this the single source of truth for the
+ * number; the hosted connector still keeps its own 25,000-character literal
+ * (`src/constants.ts`) and adopts this export in its place at a later step,
+ * not yet done as of this release. `capResult` truncates on a code-point
+ * boundary (never inside a UTF-16 surrogate pair) and appends the truncation notice, so a consumer does
+ * not have to re-implement a `slice` that can cut a surrogate pair.
+ *
+ * `MemoryToolDeps.wording` and `.writeAuthor` (STEP4-2/3/5, owner
+ * 2026-09-24) are how a SECOND server registering these tools (the hosted
+ * connector is the first consumer) speaks in its own voice: `wording`
+ * swaps "this server" for "this connector" in the three descriptions that
+ * name it and, under `auth: "oauth"`, rewords every 401/403 explanation for
+ * a user who never sees an API key; `writeAuthor` lets a supplier vouch for
+ * the end user behind a write (core: `_get_provenance`, honoured only for a
+ * SERVICE/supplier caller). Both are optional, and absent, reproduce this
+ * package's existing behaviour exactly. Full contract: docs/shared.md.
+ */
+export { registerMemoryTools, MAX_RESULT_CHARS, capResult, type ApiFetch, type MemoryToolDeps, } from "./tools.js";
+export { registerMemoryPrompts } from "./prompts.js";
+export { registerMemoryResources } from "./resources.js";
+export { SERVER_INSTRUCTIONS } from "./teaching.js";
+export { ApiError, NetworkError, UnreadableBodyError, type ApiFailure, type ErrorEnvelope, type UnreadableBody, type Wording, } from "./errors.js";
+export { type WriteAuthor } from "./requests.js";

package/dist/shared.js

@@ -0,0 +1,52 @@
+/**
+ * `@mnemoverse/mcp-memory-server/shared`: the MCP surface, for any server.
+ *
+ * ADR-025 (mnemoverse-core): this package defines the Mnemoverse MCP surface,
+ * and a server that exposes Mnemoverse memory over MCP registers these tools
+ * instead of keeping its own copy. Importing this entry point starts nothing:
+ * the stdio server lives in the package's main entry, which this file does not
+ * import.
+ *
+ *     import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+ *     import {
+ *       registerMemoryPrompts,
+ *       registerMemoryResources,
+ *       registerMemoryTools,
+ *       SERVER_INSTRUCTIONS,
+ *     } from "@mnemoverse/mcp-memory-server/shared";
+ *
+ *     const server = new McpServer({ name, version }, { instructions: SERVER_INSTRUCTIONS });
+ *     registerMemoryTools(server, { apiFetch });
+ *     registerMemoryPrompts(server);
+ *     registerMemoryResources(server, { apiFetch });
+ *
+ * `apiFetch` is the server's own way to reach the API (credential, base URL,
+ * transport). Its contract is on the `ApiFetch` type: reject with `ApiError`,
+ * `NetworkError` or `UnreadableBodyError`, because the tools branch on which.
+ *
+ * `MAX_RESULT_CHARS` and `capResult` are the tool-result size cap and the
+ * helper that applies it: 96,000 characters (24,000 tokens), the one bound
+ * both servers use for a tool result's text (`structuredContent` is not
+ * capped, OD-11). ADR-025 makes this the single source of truth for the
+ * number; the hosted connector still keeps its own 25,000-character literal
+ * (`src/constants.ts`) and adopts this export in its place at a later step,
+ * not yet done as of this release. `capResult` truncates on a code-point
+ * boundary (never inside a UTF-16 surrogate pair) and appends the truncation notice, so a consumer does
+ * not have to re-implement a `slice` that can cut a surrogate pair.
+ *
+ * `MemoryToolDeps.wording` and `.writeAuthor` (STEP4-2/3/5, owner
+ * 2026-09-24) are how a SECOND server registering these tools (the hosted
+ * connector is the first consumer) speaks in its own voice: `wording`
+ * swaps "this server" for "this connector" in the three descriptions that
+ * name it and, under `auth: "oauth"`, rewords every 401/403 explanation for
+ * a user who never sees an API key; `writeAuthor` lets a supplier vouch for
+ * the end user behind a write (core: `_get_provenance`, honoured only for a
+ * SERVICE/supplier caller). Both are optional, and absent, reproduce this
+ * package's existing behaviour exactly. Full contract: docs/shared.md.
+ */
+export { registerMemoryTools, MAX_RESULT_CHARS, capResult, } from "./tools.js";
+export { registerMemoryPrompts } from "./prompts.js";
+export { registerMemoryResources } from "./resources.js";
+export { SERVER_INSTRUCTIONS } from "./teaching.js";
+export { ApiError, NetworkError, UnreadableBodyError, } from "./errors.js";
+//# sourceMappingURL=shared.js.map

package/dist/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,SAAS,GAGV,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EACL,QAAQ,EACR,YAAY,EACZ,mBAAmB,GAKpB,MAAM,aAAa,CAAC"}

package/dist/time.d.ts

@@ -14,26 +14,15 @@
  * `safeInline` as an injected parameter precisely to avoid importing the
  * renderer), and names.ts is about printing names, not about reading clocks.
  */
+export declare function parseAsUtc(value: unknown): number | null;
 /**
- * Parse an ISO-8601 instant the way the SERVER does: an offset-less value is
- * UTC, not local time. Returns epoch milliseconds, or `null` for anything that
- * cannot be read as an instant.
- *
- * The mismatch this fixes is not cosmetic — it moved dates. West of UTC a
- * perfectly sane watermark was declared to be in the future and every clause of
- * the future-watermark note was false; east of UTC a genuinely future watermark
- * was shifted into the past and the note stayed silent, missing the one case it
- * exists for (review, 2026-08-08). On a rendered result line the same reading
- * printed `2026-08-01T23:30:00` as `2026-08-02 06:30Z` in America/Los_Angeles:
- * a memory dated to a day it was not written, with a `Z` asserting it was UTC.
- *
- * Date-only values ("2026-08-08") are already parsed as UTC by spec, so only
- * date-TIME values without an offset need the Z.
- *
- * `value` is `unknown` because both call sites read it off the wire, where the
- * response types are aspirational: `created_at` is typed as a string and can
- * arrive as a number. A value that is not a string is not an ISO-8601 instant,
- * so it is `null` here rather than a guess — `new Date(1754082281605)` is a
- * perfectly good date for a field whose contract says it is text.
+ * The instant `parseAsUtc` reads, as a string a structured consumer can trust:
+ * a value that states its own offset (`Z` or `+hh:mm`) is returned exactly as
+ * sent, so the common core value stays byte-identical; an offset-less value,
+ * which this package reads as UTC by contract, is re-emitted as the UTC
+ * ISO-8601 instant the text renders, because a consumer parsing the naive
+ * string by the ISO-8601 rule would read it as LOCAL time and land on a
+ * different instant than the text shows (review, 2026-09-23). `null` for
+ * anything `parseAsUtc` cannot read.
  */
-export declare function parseAsUtc(value: unknown): number | null;
+export declare function utcInstant(value: unknown): string | null;

package/dist/time.js

@@ -36,13 +36,31 @@
  * so it is `null` here rather than a guess — `new Date(1754082281605)` is a
  * perfectly good date for a field whose contract says it is text.
  */
+/** An explicit UTC marker or numeric offset at the end of an ISO-8601 value. */
+const OFFSET_RE = /(?:Z|[+-]\d{2}:?\d{2})$/i;
 export function parseAsUtc(value) {
     if (typeof value !== "string")
         return null;
     const s = value.trim();
-    const hasOffset = /(?:Z|[+-]\d{2}:?\d{2})$/i.test(s);
+    const hasOffset = OFFSET_RE.test(s);
     const isDateTime = /\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}/.test(s);
     const t = Date.parse(isDateTime && !hasOffset ? `${s.replace(" ", "T")}Z` : s);
     return Number.isNaN(t) ? null : t;
 }
+/**
+ * The instant `parseAsUtc` reads, as a string a structured consumer can trust:
+ * a value that states its own offset (`Z` or `+hh:mm`) is returned exactly as
+ * sent, so the common core value stays byte-identical; an offset-less value,
+ * which this package reads as UTC by contract, is re-emitted as the UTC
+ * ISO-8601 instant the text renders, because a consumer parsing the naive
+ * string by the ISO-8601 rule would read it as LOCAL time and land on a
+ * different instant than the text shows (review, 2026-09-23). `null` for
+ * anything `parseAsUtc` cannot read.
+ */
+export function utcInstant(value) {
+    const t = parseAsUtc(value);
+    if (t === null || typeof value !== "string")
+        return null;
+    return OFFSET_RE.test(value.trim()) ? value : new Date(t).toISOString();
+}
 //# sourceMappingURL=time.js.map

package/dist/time.js.map

@@ -1 +1 @@
-{"version":3,"file":"time.js","sourceRoot":"","sources":["../src/time.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3C,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IACvB,MAAM,SAAS,GAAG,0BAA0B,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACrD,MAAM,UAAU,GAAG,kCAAkC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC9D,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/E,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AACpC,CAAC"}
+{"version":3,"file":"time.js","sourceRoot":"","sources":["../src/time.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,gFAAgF;AAChF,MAAM,SAAS,GAAG,0BAA0B,CAAC;AAE7C,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3C,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IACvB,MAAM,SAAS,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpC,MAAM,UAAU,GAAG,kCAAkC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC9D,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/E,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,MAAM,CAAC,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;IAC5B,IAAI,CAAC,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACzD,OAAO,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;AAC1E,CAAC"}

package/dist/tools.d.ts

@@ -0,0 +1,134 @@
+/**
+ * The ten memory tools, 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
+ * here instead of keeping its own copy. The stdio server in src/index.ts is one
+ * such server; the hosted connector (mnemoverse-mcp-remote) is the other.
+ *
+ * What differs between servers is only how a request reaches the API: which
+ * credential it carries, where it goes, and how a transport failure is worded.
+ * That is `MemoryToolDeps.apiFetch`. Nothing in this file reads configuration
+ * or the environment.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type WriteAuthor } from "./requests.js";
+import { type Wording } from "./errors.js";
+/**
+ * How the tools reach the Mnemoverse API: send `path` (relative to the API base,
+ * e.g. "/memory/read") and resolve to the parsed JSON body.
+ *
+ * Contract every implementation must keep, because the tools branch on it:
+ * a non-2xx rejects with `ApiError` (status, core's error code and an
+ * agent-facing message), a request that never got an HTTP answer rejects with
+ * `NetworkError`, and a 2xx whose body cannot be parsed rejects with
+ * `UnreadableBodyError`. All three are exported from ./shared and defined in
+ * src/errors.ts. `options.signal` must be honoured.
+ */
+export type ApiFetch = <T = unknown>(path: string, options?: RequestInit) => Promise<T>;
+/**
+ * `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 declare function wordedApiFetch(inner: ApiFetch, wording: Wording): ApiFetch;
+/**
+ * What a server supplies when it registers the memory tools.
+ *
+ * `wording` and `writeAuthor` (STEP4-2/3/5, owner decisions 2026-09-24) are
+ * both optional, and both default to exactly this server's own behaviour: a
+ * consumer that supplies neither gets byte-identical descriptions, error
+ * text and write bodies to every release before this one. They exist for a
+ * SECOND server registering these same tools (the hosted connector,
+ * ADR-025) that needs to say "this connector" instead of "this server",
+ * speak to an OAuth user who never sees an API key, and vouch for the
+ * end user it is writing on behalf of.
+ */
+export interface MemoryToolDeps {
+    apiFetch: ApiFetch;
+    /** How this registration wants its own tool descriptions and error
+     *  explanations worded. See {@link Wording} for each field. Read at
+     *  registration time for the three descriptions that name the server,
+     *  and applied to every `ApiError`/`NetworkError`/`UnreadableBodyError`
+     *  the consumer's `apiFetch` rejects with (see {@link wordedApiFetch}),
+     *  so the consumer states it once, here. Passing the same value to the
+     *  error constructors inside `apiFetch` is allowed and changes nothing. */
+    wording?: Wording;
+    /**
+     * Supplier-vouched authorship for `memory_write` (STEP4-5). Called once
+     * per write, with no arguments; a returned value is sent as the request
+     * body's `author` field EXACTLY as returned (this package applies no
+     * normalisation beyond a `typeof` guard; core re-normalises server-side,
+     * see {@link WriteAuthor}). Returning `undefined`, or omitting this
+     * dependency entirely, sends the body this package has always sent: the
+     * stdio server's own requests are exactly this case, and do not change.
+     *
+     * Core honours `author` ONLY for a SERVICE/supplier caller and IGNORES it
+     * for an OIDC end-user (mnemoverse-core src/mnemo/api/routes.py:211-276,
+     * `_get_provenance`, verified 2026-09-24), so this dependency is useful
+     * only to a server that authenticates to core as a supplier vouching for
+     * someone else, not to an end-user's own key.
+     */
+    writeAuthor?: () => WriteAuthor | undefined;
+}
+export declare const MAX_RESULT_CHARS: number;
+/**
+ * Truncate a result string to MAX_RESULT_CHARS, appending a notice if truncated.
+ * Required by Claude Connectors Directory submission policy.
+ *
+ * Defensive against splitting UTF-16 surrogate pairs: if the character right
+ * 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.
+ */
+export declare function capResult(text: string, moreHint?: string): string;
+/**
+ * The sentence behind {@link unreadableAnswerReply}, exported so the memory
+ * resource (src/resources.ts) says the same thing about an unreadable answer
+ * rather than keeping its own copy.
+ *
+ * The tail attributes the unreadable 200 to "whatever answered this call", not
+ * to "the memory service" — this client cannot establish WHO answered: a
+ * gateway, a proxy, or the endpoint a mis-set MNEMOVERSE_API_URL points at
+ * produces the same 200 with an unrecognised body (truth re-verification,
+ * 2026-08-09). Pinned in test/handlers.test.ts.
+ */
+export declare function unreadableAnswerText(subject: string, notA: string, absence: string, extra?: string): string;
+/**
+ * A success result carrying both a text block and `structuredContent`, which
+ * is what a tool with a declared `outputSchema` must return, or the SDK
+ * itself rejects the call. `validateToolOutput` in the installed SDK
+ * (node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:185-207)
+ * turns a non-error, text-only result into an `isError` "Output validation
+ * error: … has an output schema but no structured content was provided", the
+ * moment a tool declares that schema, even though the same text alone was a
+ * fine answer the day before the schema was added. Pinned against that
+ * installed SDK in test/structured-output.test.ts.
+ *
+ * Deliberately dumb: it does not call `capResult` or `withDomainEscapeLegend`
+ * itself. Every tool already measures and caps its own text with a per-tool
+ * hint and applies the legend after the cap (see memory_read below), so a
+ * helper that capped again would double-truncate; callers pass `text`
+ * already finished.
+ */
+export declare function structured(text: string, data: Record<string, unknown>): {
+    content: [{
+        type: "text";
+        text: string;
+    }];
+    structuredContent: Record<string, unknown>;
+};
+/**
+ * Register the ten memory tools on `server`. Call once per server instance.
+ * `deps.apiFetch` is the only way the tools reach the API.
+ */
+export declare function registerMemoryTools(server: McpServer, deps: MemoryToolDeps): void;