@mnemoverse/mcp-memory-server 0.10.1 → 0.11.0

package/dist/render.js

@@ -11,7 +11,7 @@
  * the line are simply omitted.
  */
 import { MAX_DOMAIN_TAG_LITERAL, exactLiteral } from "./names.js";
-import { parseAsUtc } from "./time.js";
+import { parseAsUtc, utcInstant } from "./time.js";
 /**
  * Sanitize a string for inline interpolation into tool output (CN-032: hostile
  * connectors choose their own agent_name). The single implementation, imported
@@ -60,17 +60,32 @@ export function safeInline(s, cap = 200) {
         .slice(0, cap);
 }
 /**
- * ` [by X]` / ` [by X · external]` — agent identity only, never the human
- * `principal` (may be an email / PII), even though the response carries it.
+ * "X" / "X · external": agent identity only, never the human `principal`
+ * (may be an email / PII), even though the response carries it. Empty string
+ * when there is no renderable name.
+ *
+ * Extracted from `formatAuthorTag` (S4, structured-output plan) so
+ * `structuredItem` below can put the same sanitised name into
+ * `structuredContent.author` without re-deriving it, and so the two never
+ * drift: `formatAuthorTag` now builds its bracketed text FROM this value
+ * rather than computing its own copy.
  */
-export function formatAuthorTag(p) {
+export function authorName(p) {
     if (!p)
         return "";
     const raw = p.agent_name || p.agent || p.client_env || "";
     const who = safeInline(raw, 64);
     if (!who)
         return "";
-    return p.is_external ? ` [by ${who} · external]` : ` [by ${who}]`;
+    return p.is_external ? `${who} · external` : who;
+}
+/**
+ * ` [by X]` / ` [by X · external]` — agent identity only, never the human
+ * `principal` (may be an email / PII), even though the response carries it.
+ */
+export function formatAuthorTag(p) {
+    const who = authorName(p);
+    return who ? ` [by ${who}]` : "";
 }
 /**
  * ` @"domain"` — which store the memory actually came from, printed so it can
@@ -170,6 +185,45 @@ export function formatReadItem(item, index) {
     const head = `${index + 1}. ${content}${concepts}${formatDomainTag(item?.domain)}${formatAuthorTag(item?.provenance)}${formatDateTag(item?.created_at)}`;
     return item?.atom_id ? `${head}\n   id: ${item.atom_id}` : head;
 }
+/**
+ * The `structuredContent` twin of {@link formatReadItem} (S4, structured-output
+ * plan): the same item, shaped for memory_read's `outputSchema` instead of for
+ * a line of text.
+ *
+ * PRECONDITION, enforced by the caller (src/tools.ts) before this is ever
+ * invoked: `item.atom_id`, `item.content` and `item.domain` are all strings.
+ * core's MemoryItemSchema sends all three on every item; a response that
+ * doesn't is caught by the handler's item guard and answered with
+ * `unreadableAnswerReply` before `structuredItem` is reached, so the casts
+ * below are a documented precondition, not a runtime assumption made here.
+ *
+ * `content` is carried EXACTLY, uncapped and unnormalised (decision OD-11,
+ * owner, 2026-09-23): unlike the text line, which goes through `capResult`
+ * for the 25K-token result-size cap, `structuredContent` is not capped
+ * anywhere else in this package either (memory_write's `reason` is the only
+ * normalised structured field, and that's control/bidi/zero-width hygiene on
+ * a diagnostic string, not a length cap on the memory itself); a client
+ * reading structured data reads `content` as the stored memory, and a
+ * silently shorter value there would be a different kind of lie than a
+ * truncated text block with a notice at the end.
+ */
+export function structuredItem(item) {
+    const author = authorName(item.provenance);
+    const created = utcInstant(item.created_at);
+    return {
+        memory_id: item.atom_id,
+        content: item.content,
+        domain: item.domain,
+        // The rule the text already applies through formatDateTag: a value that
+        // does not parse as a date is no creation instant, whatever its type, and
+        // the field promises a UTC ISO-8601 instant. A value that states its
+        // offset is carried as sent; an offset-less one (UTC by contract) is
+        // re-emitted as the UTC instant the text renders, since a consumer
+        // would otherwise read it as local time (src/time.ts, utcInstant).
+        ...(created !== null ? { created_at: created } : {}),
+        ...(author ? { author } : {}),
+    };
+}
 /**
  * One memory_list_recent line — a feed entry, not a search hit: no
  * relevance, date leads because the feed is ORDERED by it.
@@ -183,6 +237,14 @@ export function formatRecentItem(item, index) {
     const head = `${index + 1}. ${date ? `[${date}] ` : ""}${content}${concepts}${formatDomainTag(item?.domain)}${formatAuthorTag(item?.provenance)}`;
     return item?.atom_id ? `${head}\n   id: ${item.atom_id}` : head;
 }
+/**
+ * The shape of a continuation token this client is willing to pass on
+ * (CN-032): the server-supplied cursor is opaque, so this is an allowlist
+ * of bytes, not a format. One constant for BOTH surfaces, the text (below)
+ * and `structuredContent.next_cursor` (src/tools.ts), so they cannot
+ * disagree about which token is passable.
+ */
+export const CURSOR_RE = /^[A-Za-z0-9_=-]{1,512}$/;
 /**
  * Full feed page: items newest-first + how to continue / that it's over.
  *
@@ -194,6 +256,9 @@ export function formatRecentItem(item, index) {
  * 2026-08-08). Once-per-answer still holds — withDomainEscapeLegend is
  * at-most-once by construction (src/names.ts).
  */
+// `nextCursor` is typed loosely on purpose: it is a server-supplied wire
+// value, and a number where a string was promised must fail the gate below
+// rather than be coerced into it by the regex test (review, 2026-09-23).
 export function formatRecentPage(items, nextCursor) {
     const lines = items.map((it, i) => formatRecentItem(it, i));
     // Defense-in-depth (CN-032 posture): the cursor is server-supplied and
@@ -218,7 +283,7 @@ export function formatRecentPage(items, nextCursor) {
     if (nextCursor == null) {
         tail = `\n\n(end of feed — nothing older)`;
     }
-    else if (/^[A-Za-z0-9_=-]{1,512}$/.test(nextCursor)) {
+    else if (typeof nextCursor === "string" && CURSOR_RE.test(nextCursor)) {
         tail = `\n\nMore older entries exist — pass cursor: ${nextCursor}`;
     }
     else {

package/dist/render.js.map

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

package/dist/requests.d.ts

@@ -69,3 +69,47 @@ export declare function recentRequestBody(a: RecentArgs): Record<string, unknown
 /** memory_write. `"general"` is the server-side default made explicit, and is
  * what 0.8.0 sent — NOT a normalisation of the caller's value. */
 export declare function writeRequestBody(a: WriteArgs): Record<string, unknown>;
+/**
+ * Refuse a docs placeholder key from CONFIGURATION ALONE, before any tool
+ * call sends it anywhere.
+ *
+ * WHY THIS EXISTS. The engine sees this server calling it again and again
+ * with the example key from the install snippets. The agent got a 401, got
+ * this server's generic replace-the-key sentence, and called again. A value this client can recognise as a placeholder WITHOUT any
+ * request is still worth refusing before the network, exactly as
+ * `refuseInsecureBaseUrl` (src/index.ts) refuses an insecure
+ * MNEMOVERSE_API_URL before the network, for the same reason: a config-only
+ * guard is checked once and costs nothing, while a wasted round trip costs a
+ * rate-limited request every time an agent cannot help but retry.
+ *
+ * FIRES ONLY FOR VALUES THAT ARE CERTAINLY PLACEHOLDERS: two shapes, and
+ * nothing else, however odd:
+ *
+ *   (a) mk_live_ followed by an upper-case label (mk_live_YOUR_KEY,
+ *       mk_live_USER_KEY, mk_live_CODING_AGENT_KEY), the same shape the
+ *       engine itself classifies as placeholder_key.
+ *   (b) mk_live_ followed only by the letter x, at least four of them,
+ *       either case (mk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx), the
+ *       template value shipped in src/configs/source.json.
+ *
+ * A self-hosted static-auth deployment can use an arbitrary key that does
+ * not start with mk_live_ at all, and a TRUNCATED real key (mk_live_deadbeef,
+ * say) must still reach the engine, whose answer is more precise than a
+ * local guess would be. So both a mixed-case label (mk_live_Your_Key) and
+ * anything shaped like a real key are left alone here on purpose, same as
+ * every other value this function has never seen.
+ *
+ * PURE AND EXPORTED, colocated with the request builders rather than with
+ * `refuseInsecureBaseUrl` itself, because that one needs a `URL` parse this
+ * module has no other reason to import (the shape of the guard is the same,
+ * the machinery differs). `apiFetch` in src/index.ts evaluates this once into
+ * a module constant next to `BASE_URL_REFUSAL`, and checks both at the same
+ * two call sites: inside `apiFetch`, and inside the startup probe.
+ *
+ * `KEYS_URL` is imported from src/errors.ts rather than repeated here as a
+ * second literal, the same console page a 401 already points at.
+ */
+export declare function refusePlaceholderKey(key: string): {
+    toolCall: string;
+    startupLog: string;
+} | undefined;

package/dist/requests.js

@@ -30,6 +30,11 @@
  * here as a second surface needing the same treatment, was withdrawn
  * 2026-08-20 — deletion is administrative-only now.)
  */
+// KEYS_URL is imported for refusePlaceholderKey at the bottom of this file:
+// a config-only guard that otherwise has nothing to do with request bodies,
+// but needs the same console URL a 401 already points at (src/errors.ts) and
+// is documented at its own definition rather than here.
+import { KEYS_URL } from "./errors.js";
 /**
  * The scope actually searched: what core receives, and therefore the only value
  * any message about the result may describe.
@@ -75,4 +80,65 @@ export function writeRequestBody(a) {
         domain: a.domain || "general",
     };
 }
+/**
+ * Refuse a docs placeholder key from CONFIGURATION ALONE, before any tool
+ * call sends it anywhere.
+ *
+ * WHY THIS EXISTS. The engine sees this server calling it again and again
+ * with the example key from the install snippets. The agent got a 401, got
+ * this server's generic replace-the-key sentence, and called again. A value this client can recognise as a placeholder WITHOUT any
+ * request is still worth refusing before the network, exactly as
+ * `refuseInsecureBaseUrl` (src/index.ts) refuses an insecure
+ * MNEMOVERSE_API_URL before the network, for the same reason: a config-only
+ * guard is checked once and costs nothing, while a wasted round trip costs a
+ * rate-limited request every time an agent cannot help but retry.
+ *
+ * FIRES ONLY FOR VALUES THAT ARE CERTAINLY PLACEHOLDERS: two shapes, and
+ * nothing else, however odd:
+ *
+ *   (a) mk_live_ followed by an upper-case label (mk_live_YOUR_KEY,
+ *       mk_live_USER_KEY, mk_live_CODING_AGENT_KEY), the same shape the
+ *       engine itself classifies as placeholder_key.
+ *   (b) mk_live_ followed only by the letter x, at least four of them,
+ *       either case (mk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx), the
+ *       template value shipped in src/configs/source.json.
+ *
+ * A self-hosted static-auth deployment can use an arbitrary key that does
+ * not start with mk_live_ at all, and a TRUNCATED real key (mk_live_deadbeef,
+ * say) must still reach the engine, whose answer is more precise than a
+ * local guess would be. So both a mixed-case label (mk_live_Your_Key) and
+ * anything shaped like a real key are left alone here on purpose, same as
+ * every other value this function has never seen.
+ *
+ * PURE AND EXPORTED, colocated with the request builders rather than with
+ * `refuseInsecureBaseUrl` itself, because that one needs a `URL` parse this
+ * module has no other reason to import (the shape of the guard is the same,
+ * the machinery differs). `apiFetch` in src/index.ts evaluates this once into
+ * a module constant next to `BASE_URL_REFUSAL`, and checks both at the same
+ * two call sites: inside `apiFetch`, and inside the startup probe.
+ *
+ * `KEYS_URL` is imported from src/errors.ts rather than repeated here as a
+ * second literal, the same console page a 401 already points at.
+ */
+export function refusePlaceholderKey(key) {
+    const isLabelledPlaceholder = /^mk_live_[A-Z][A-Z_]*$/.test(key);
+    const isTemplatePlaceholder = /^mk_live_[xX]{4,}$/.test(key);
+    if (!isLabelledPlaceholder && !isTemplatePlaceholder)
+        return undefined;
+    return {
+        toolCall: "Mnemoverse: this tool did not run, because MNEMOVERSE_API_KEY is " +
+            "still the example value from the documentation, not a real key. " +
+            "Nothing was sent: this client refuses the call instead. This is the " +
+            "user's configuration, not a fault of the key, the network or the " +
+            `service. Tell them to create a key at ${KEYS_URL}, put it in the ` +
+            "MCP client config in place of the placeholder, and restart the MCP " +
+            "server. Do not retry until then; every memory tool will fail the " +
+            "same way until it is replaced.",
+        startupLog: "Mnemoverse: startup key check SKIPPED, and nothing was sent. " +
+            "MNEMOVERSE_API_KEY is still the example value from the " +
+            `documentation, not a real key. Create one at ${KEYS_URL}, put it in ` +
+            "the MCP client config in place of the placeholder, and restart. " +
+            "Every memory tool will fail until it is replaced.",
+    };
+}
 //# sourceMappingURL=requests.js.map

package/dist/requests.js.map

@@ -1 +1 @@
-{"version":3,"file":"requests.js","sourceRoot":"","sources":["../src/requests.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AA2BH;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,MAAe;IAC3C,OAAO,MAAM,IAAI,SAAS,CAAC;AAC7B,CAAC;AAED;mEACmE;AACnE,MAAM,UAAU,eAAe,CAAC,CAAW;IACzC,OAAO;QACL,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,KAAK,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC;QACnB,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC;QAC/B,oBAAoB,EAAE,IAAI;QAC1B,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACtC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACtC,GAAG,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAClE,CAAC;AACJ,CAAC;AAED,0BAA0B;AAC1B,MAAM,UAAU,iBAAiB,CAAC,CAAa;IAC7C,OAAO;QACL,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC;QAC/B,KAAK,EAAE,CAAC,CAAC,KAAK,IAAI,SAAS;QAC3B,KAAK,EAAE,CAAC,CAAC,KAAK,IAAI,SAAS;QAC3B,cAAc,EAAE,CAAC,CAAC,cAAc,IAAI,SAAS;QAC7C,KAAK,EAAE,CAAC,CAAC,KAAK,IAAI,EAAE;QACpB,MAAM,EAAE,CAAC,CAAC,MAAM,IAAI,SAAS;KAC9B,CAAC;AACJ,CAAC;AAED;kEACkE;AAClE,MAAM,UAAU,gBAAgB,CAAC,CAAY;IAC3C,OAAO;QACL,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,QAAQ,EAAE,CAAC,CAAC,QAAQ,IAAI,EAAE;QAC1B,MAAM,EAAE,CAAC,CAAC,MAAM,IAAI,SAAS;KAC9B,CAAC;AACJ,CAAC"}
+{"version":3,"file":"requests.js","sourceRoot":"","sources":["../src/requests.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,4EAA4E;AAC5E,4EAA4E;AAC5E,6EAA6E;AAC7E,wDAAwD;AACxD,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AA2BvC;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,MAAe;IAC3C,OAAO,MAAM,IAAI,SAAS,CAAC;AAC7B,CAAC;AAED;mEACmE;AACnE,MAAM,UAAU,eAAe,CAAC,CAAW;IACzC,OAAO;QACL,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,KAAK,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC;QACnB,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC;QAC/B,oBAAoB,EAAE,IAAI;QAC1B,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACtC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACtC,GAAG,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAClE,CAAC;AACJ,CAAC;AAED,0BAA0B;AAC1B,MAAM,UAAU,iBAAiB,CAAC,CAAa;IAC7C,OAAO;QACL,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC;QAC/B,KAAK,EAAE,CAAC,CAAC,KAAK,IAAI,SAAS;QAC3B,KAAK,EAAE,CAAC,CAAC,KAAK,IAAI,SAAS;QAC3B,cAAc,EAAE,CAAC,CAAC,cAAc,IAAI,SAAS;QAC7C,KAAK,EAAE,CAAC,CAAC,KAAK,IAAI,EAAE;QACpB,MAAM,EAAE,CAAC,CAAC,MAAM,IAAI,SAAS;KAC9B,CAAC;AACJ,CAAC;AAED;kEACkE;AAClE,MAAM,UAAU,gBAAgB,CAAC,CAAY;IAC3C,OAAO;QACL,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,QAAQ,EAAE,CAAC,CAAC,QAAQ,IAAI,EAAE;QAC1B,MAAM,EAAE,CAAC,CAAC,MAAM,IAAI,SAAS;KAC9B,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,UAAU,oBAAoB,CAClC,GAAW;IAEX,MAAM,qBAAqB,GAAG,wBAAwB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACjE,MAAM,qBAAqB,GAAG,oBAAoB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC7D,IAAI,CAAC,qBAAqB,IAAI,CAAC,qBAAqB;QAAE,OAAO,SAAS,CAAC;IACvE,OAAO;QACL,QAAQ,EACN,mEAAmE;YACnE,kEAAkE;YAClE,sEAAsE;YACtE,mEAAmE;YACnE,yCAAyC,QAAQ,kBAAkB;YACnE,qEAAqE;YACrE,mEAAmE;YACnE,gCAAgC;QAClC,UAAU,EACR,+DAA+D;YAC/D,yDAAyD;YACzD,gDAAgD,QAAQ,cAAc;YACtE,kEAAkE;YAClE,mDAAmD;KACtD,CAAC;AACJ,CAAC"}

package/dist/resources.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 { type McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type MemoryToolDeps } from "./tools.js";
+/**
+ * Register the `memory://item/{memory_id}` resource on `server`. It reaches the
+ * API only through `deps.apiFetch`, like the tools.
+ */
+export declare function registerMemoryResources(server: McpServer, deps: MemoryToolDeps): void;

package/dist/resources.js

@@ -0,0 +1,94 @@
+/**
+ * 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 } 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) {
+    const { apiFetch } = deps;
+    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":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,gBAAgB,EAAkB,MAAM,yCAAyC,CAAC;AAC3F,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,oBAAoB,EAAuB,MAAM,YAAY,CAAC;AAEvE,yFAAyF;AACzF,MAAM,kBAAkB,GAAG,CAAC,KAAK,CAAC;AAElC;;;;;GAKG;AACH,SAAS,UAAU,CAAC,OAAe;IACjC,IAAI,CAAC;QACH,OAAO,kBAAkB,CAAC,OAAO,CAAC,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,OAAO,CAAC;IACjB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAiB,EAAE,IAAoB;IAC7E,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC;IAE1B,MAAM,CAAC,gBAAgB,CACrB,aAAa,EACb,IAAI,gBAAgB,CAAC,2BAA2B,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,EACtE;QACE,KAAK,EAAE,cAAc;QACrB,WAAW,EACT,uKAAuK;QACzK,QAAQ,EAAE,kBAAkB;KAC7B,EACD,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,EAAE;QACvB,MAAM,EAAE,GAAG,UAAU,CAAC,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC;QACnD,IAAI,MAAe,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,GAAG,MAAM,QAAQ,CAAU,iBAAiB,kBAAkB,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QAC9E,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,8DAA8D;YAC9D,oEAAoE;YACpE,wEAAwE;YACxE,8DAA8D;YAC9D,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACjE,MAAM,IAAI,GACR,GAAG,YAAY,QAAQ,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC;YAC/F,MAAM,IAAI,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACpC,CAAC;QACD,qEAAqE;QACrE,uEAAuE;QACvE,uEAAuE;QACvE,yEAAyE;QACzE,sDAAsD;QACtD,MAAM,IAAI,GAAG,MAAsE,CAAC;QACpF,IACE,OAAO,IAAI,KAAK,QAAQ;YACxB,IAAI,KAAK,IAAI;YACb,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ;YAChC,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,EAC/B,CAAC;YACD,MAAM,IAAI,QAAQ,CAChB,SAAS,CAAC,aAAa,EACvB,oBAAoB,CAAC,YAAY,EAAE,YAAY,EAAE,qBAAqB,CAAC,CACxE,CAAC;QACJ,CAAC;QACD,OAAO;YACL,QAAQ,EAAE;gBACR;oBACE,GAAG,EAAE,GAAG,CAAC,IAAI;oBACb,QAAQ,EAAE,kBAAkB;oBAC5B,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;wBACnB,SAAS,EAAE,OAAO,IAAI,CAAC,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE;wBACrD,OAAO,EAAE,IAAI,CAAC,OAAO;wBACrB,MAAM,EAAE,IAAI,CAAC,MAAM;qBACpB,CAAC;iBACH;aACF;SACF,CAAC;IACJ,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/shared.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `@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.
+ */
+export { registerMemoryTools, 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, } from "./errors.js";

package/dist/shared.js

@@ -0,0 +1,32 @@
+/**
+ * `@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.
+ */
+export { registerMemoryTools } 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;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,mBAAmB,EAAsC,MAAM,YAAY,CAAC;AACrF,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,GAIpB,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,71 @@
+/**
+ * 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";
+/**
+ * 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>;
+/** What a server supplies when it registers the memory tools. */
+export interface MemoryToolDeps {
+    apiFetch: ApiFetch;
+}
+/**
+ * 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;