@hasna/mementos 0.16.0 → 0.17.0

package/dist/cli/structured-json.d.ts

@@ -0,0 +1,54 @@
+import type { Agent, Memory, Project, MemorySearchResult } from "../types/index.js";
+export declare const STRUCTURED_PAGE_MAX_ROWS = 1000;
+export declare const STRUCTURED_ALL_MAX_ROWS = 100000;
+export declare const STRUCTURED_DEFAULT_MAX_BYTES: number;
+export declare const STRUCTURED_FULL_MAX_BYTES: number;
+export declare const STRUCTURED_ALL_MAX_BYTES: number;
+export declare const STRUCTURED_MIN_MAX_BYTES = 1024;
+export type StructuredDetail = "compact" | "full";
+export interface StructuredCollectionMeta {
+    receipt: string;
+    count: number;
+    limit: number | null;
+    offset: number;
+    next_cursor: number | null;
+    has_more: boolean;
+    complete: boolean;
+    all: boolean;
+    detail: StructuredDetail;
+    max_rows: number;
+    max_bytes: number;
+    response_bytes: number;
+    truncated: boolean;
+    truncation_reason: "limit" | "cursor" | "max_bytes" | null;
+    omitted_from_page: number;
+    next_arguments: Record<string, unknown> | null;
+    continuation_scope: "unchanged_snapshot";
+}
+export declare function structuredMaxBytes(value: unknown, opts: {
+    all: boolean;
+    detail: StructuredDetail;
+}): number;
+export declare function structuredPageLimit(value: unknown, fallback: number): number;
+export declare function compactMemory(memory: Memory, opts?: {
+    history?: boolean;
+}): Record<string, unknown>;
+export declare function compactProject(project: Project): Record<string, unknown>;
+export declare function compactAgent(agent: Agent): Record<string, unknown>;
+export declare function compactSearchResult(result: MemorySearchResult): Record<string, unknown>;
+interface CollectionArgs<T> {
+    collection: string;
+    receipt: string;
+    items: T[];
+    offset: number;
+    limit: number;
+    sourceHasMore: boolean;
+    all: boolean;
+    detail: StructuredDetail;
+    maxBytes: number;
+    nextArguments?: Record<string, unknown>;
+    includeDetailInNextArguments?: boolean;
+}
+export declare function structuredCollectionOutput<T>(args: CollectionArgs<T>): string;
+export {};
+//# sourceMappingURL=structured-json.d.ts.map

package/dist/cli/structured-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured-json.d.ts","sourceRoot":"","sources":["../../src/cli/structured-json.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEpF,eAAO,MAAM,wBAAwB,OAAQ,CAAC;AAC9C,eAAO,MAAM,uBAAuB,SAAU,CAAC;AAC/C,eAAO,MAAM,4BAA4B,QAAY,CAAC;AACtD,eAAO,MAAM,yBAAyB,QAAY,CAAC;AACnD,eAAO,MAAM,wBAAwB,QAAmB,CAAC;AACzD,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAE7C,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,MAAM,CAAC;AAElD,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,GAAG,EAAE,OAAO,CAAC;IACb,MAAM,EAAE,gBAAgB,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,OAAO,CAAC;IACnB,iBAAiB,EAAE,OAAO,GAAG,QAAQ,GAAG,WAAW,GAAG,IAAI,CAAC;IAC3D,iBAAiB,EAAE,MAAM,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC/C,kBAAkB,EAAE,oBAAoB,CAAC;CAC1C;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,IAAI,EAAE;IAAE,GAAG,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,gBAAgB,CAAA;CAAE,GAC/C,MAAM,CAkBR;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAM5E;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAkBvG;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASxE;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASlE;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAavF;AAED,UAAU,cAAc,CAAC,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,CAAC,EAAE,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,OAAO,CAAC;IACvB,GAAG,EAAE,OAAO,CAAC;IACb,MAAM,EAAE,gBAAgB,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,4BAA4B,CAAC,EAAE,OAAO,CAAC;CACxC;AAsDD,wBAAgB,0BAA0B,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,MAAM,CA6B7E"}

package/dist/lib/conversations-transport.d.ts

@@ -0,0 +1,21 @@
+import { type CredentialChainOptions } from "@hasna/contracts/client";
+export interface ConversationsTransportOptions {
+    env?: Record<string, string | undefined>;
+    credentials?: CredentialChainOptions;
+    fetch?: typeof fetch;
+}
+export interface ConversationsTransport {
+    baseUrl: string;
+    apiKey: string | null;
+    localExplicit: boolean;
+    fetch: typeof fetch;
+}
+/**
+ * Resolve Conversations through the shared hosted credential chain. There is
+ * no implicit localhost default. A caller may retain an explicitly configured
+ * loopback URL for a deliberate local/test setup; ambient hosted credentials
+ * are never attached to that caller-chosen authority.
+ */
+export declare function resolveConversationsTransport(options?: ConversationsTransportOptions): ConversationsTransport;
+export declare function conversationsRequest(path: string, init?: RequestInit, options?: ConversationsTransportOptions): Promise<Response>;
+//# sourceMappingURL=conversations-transport.d.ts.map

package/dist/lib/conversations-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversations-transport.d.ts","sourceRoot":"","sources":["../../src/lib/conversations-transport.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,sBAAsB,EAC5B,MAAM,yBAAyB,CAAC;AAEjC,MAAM,WAAW,6BAA6B;IAC5C,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,WAAW,CAAC,EAAE,sBAAsB,CAAC;IACrC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,aAAa,EAAE,OAAO,CAAC;IACvB,KAAK,EAAE,OAAO,KAAK,CAAC;CACrB;AAoBD;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,GAAE,6BAAkC,GAC1C,sBAAsB,CA2BxB;AAED,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,WAAgB,EACtB,OAAO,GAAE,6BAAkC,GAC1C,OAAO,CAAC,QAAQ,CAAC,CASnB"}

package/dist/lib/export-v1.d.ts

@@ -19,6 +19,8 @@ export interface ExportV1Entry {
  * Returns an array of export entries (caller serializes to JSONL).
  */
 export declare function exportV1(filter?: MemoryFilter, db?: Database): ExportV1Entry[];
+/** Build portable v1 entries for an already bounded memory page. */
+export declare function exportV1Entries(memories: Memory[], db?: Database): ExportV1Entry[];
 /**
  * Serialize export entries to JSONL string (one JSON object per line).
  */

package/dist/lib/export-v1.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"export-v1.d.ts","sourceRoot":"","sources":["../../src/lib/export-v1.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAI9D,OAAO,EAAE,aAAa,IAAI,QAAQ,EAAE,MAAM,eAAe,CAAC;AAG1D,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,oBAAoB,CAAC;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,KAAK,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC,CAAC;CACJ;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CACtB,MAAM,CAAC,EAAE,YAAY,EACrB,EAAE,CAAC,EAAE,QAAQ,GACZ,aAAa,EAAE,CA6BjB;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,MAAM,CAExD;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,EAAE,CAKxD"}
+{"version":3,"file":"export-v1.d.ts","sourceRoot":"","sources":["../../src/lib/export-v1.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAI9D,OAAO,EAAE,aAAa,IAAI,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE1D,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,oBAAoB,CAAC;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,KAAK,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC,CAAC;CACJ;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CACtB,MAAM,CAAC,EAAE,YAAY,EACrB,EAAE,CAAC,EAAE,QAAQ,GACZ,aAAa,EAAE,CAGjB;AAED,oEAAoE;AACpE,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAAE,EAClB,EAAE,CAAC,EAAE,QAAQ,GACZ,aAAa,EAAE,CA0BjB;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,MAAM,CAExD;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,EAAE,CAKxD"}

package/dist/mcp/index.js

@@ -12917,38 +12917,102 @@ var init_zod = __esm(() => {
   init_external();
 });
 
+// src/lib/conversations-transport.ts
+import {
+  clientTransportEnvKeys as clientTransportEnvKeys3,
+  resolveClientTransport as resolveClientTransport2,
+  resolveCredential as resolveCredential2,
+  toV1BaseUrl as toV1BaseUrl2
+} from "@hasna/contracts/client";
+function explicitApiUrl(env2) {
+  const keys = clientTransportEnvKeys3("conversations").apiUrlKeys;
+  for (const key of keys) {
+    const value = env2[key]?.trim();
+    if (value)
+      return value;
+  }
+  return;
+}
+function isLoopbackUrl(value) {
+  try {
+    const host = new URL(value).hostname.replace(/^\[|\]$/g, "").toLowerCase();
+    return host === "localhost" || host === "::1" || /^127\./.test(host);
+  } catch {
+    return false;
+  }
+}
+function resolveConversationsTransport(options = {}) {
+  const env2 = options.env ?? process.env;
+  const explicitUrl = explicitApiUrl(env2);
+  if (explicitUrl && isLoopbackUrl(explicitUrl)) {
+    return {
+      baseUrl: toV1BaseUrl2(explicitUrl),
+      apiKey: null,
+      localExplicit: true,
+      fetch: options.fetch ?? globalThis.fetch.bind(globalThis)
+    };
+  }
+  const credential = resolveCredential2("conversations", env2, options.credentials ?? {});
+  if (!credential) {
+    throw new Error("Conversations notifications require a hosted credential from the Keychain, ~/.hasna/conversations/config/credentials, or HASNA_CONVERSATIONS_API_KEY; refusing localhost fallback");
+  }
+  const resolution = resolveClientTransport2("conversations", env2, {
+    credentials: { ...options.credentials ?? {}, apiKey: credential.apiKey }
+  });
+  return {
+    baseUrl: toV1BaseUrl2(resolution.baseUrl),
+    apiKey: credential.apiKey,
+    localExplicit: false,
+    fetch: options.fetch ?? globalThis.fetch.bind(globalThis)
+  };
+}
+async function conversationsRequest(path, init = {}, options = {}) {
+  const transport = resolveConversationsTransport(options);
+  const headers = new Headers(init.headers ?? {});
+  if (transport.apiKey) {
+    headers.set("x-api-key", transport.apiKey);
+    headers.set("Authorization", `Bearer ${transport.apiKey}`);
+  }
+  const route = path.startsWith("/") ? path : `/${path}`;
+  return transport.fetch(`${transport.baseUrl}${route}`, { ...init, headers });
+}
+var init_conversations_transport = () => {};
+
 // src/mcp/memory-broadcast.ts
 var exports_memory_broadcast = {};
 __export(exports_memory_broadcast, {
   broadcastSharedMemory: () => broadcastSharedMemory
 });
-async function broadcastSharedMemory(memory, savingAgentId) {
+async function broadcastSharedMemory(memory, savingAgentId, transport = {}) {
   if (!memory.project_id)
     return;
   try {
-    const listRes = await fetch(`${CONVERSATIONS_API}/api/v1/agents?active=true&project_id=${memory.project_id}`, {
-      signal: AbortSignal.timeout(3000)
+    const query = new URLSearchParams({
+      online_only: "true",
+      project_id: memory.project_id
     });
+    const listRes = await conversationsRequest(`/agents?${query}`, {
+      signal: AbortSignal.timeout(3000)
+    }, transport);
     if (!listRes.ok)
       return;
     const { agents } = await listRes.json();
-    if (!agents?.length)
-      return;
-    const otherAgents = agents.filter((a) => a.id !== savingAgentId);
-    if (!otherAgents.length)
+    const otherAgents = (agents ?? []).filter((agent) => agent.id !== savingAgentId);
+    if (otherAgents.length === 0)
       return;
     const notification = `[Memory Update] Agent ${savingAgentId} saved shared memory: "${memory.key}" \u2014 ${memory.summary || memory.value.slice(0, 100)}. Consider recalling this memory if relevant to your current task.`;
-    await Promise.all(otherAgents.map((agent) => fetch(`${CONVERSATIONS_API}/api/v1/messages`, {
+    await Promise.all(otherAgents.map((agent) => conversationsRequest("/messages", {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({ from: savingAgentId, to: agent.id, content: notification }),
       signal: AbortSignal.timeout(3000)
-    }).catch(() => {})));
+    }, transport).catch(() => {
+      return;
+    })));
   } catch {}
 }
-var CONVERSATIONS_API;
 var init_memory_broadcast = __esm(() => {
-  CONVERSATIONS_API = process.env.CONVERSATIONS_API_URL || "http://localhost:7020";
+  init_conversations_transport();
 });
 
 // src/audit-contract.ts
@@ -13612,18 +13676,21 @@ var exports_export_v1 = {};
 __export(exports_export_v1, {
   toJsonl: () => toJsonl,
   fromJsonl: () => fromJsonl,
+  exportV1Entries: () => exportV1Entries,
   exportV1: () => exportV1
 });
 function exportV1(filter, db) {
-  const d = db || getDatabase();
-  const memories = listMemories(filter, d);
+  const memories = listMemoriesBounded(filter ?? {}, undefined, db).rows;
+  return exportV1Entries(memories, db);
+}
+function exportV1Entries(memories, db) {
   const exportedAt = new Date().toISOString();
   return memories.map((memory) => {
     let entityLinks = [];
     try {
-      const links = getEntityMemoryLinks(undefined, memory.id, d);
+      const links = getEntityMemoryLinks(undefined, memory.id, db);
       entityLinks = links.map((link) => {
-        const entity = getEntity(link.entity_id, d);
+        const entity = getEntity(link.entity_id, db);
         return {
           entity_name: entity?.name ?? "unknown",
           entity_type: entity?.type ?? "unknown",
@@ -13651,7 +13718,6 @@ var init_export_v1 = __esm(() => {
   init_memories();
   init_entity_memories();
   init_entities();
-  init_database();
 });
 
 // src/lib/injection-project.ts
@@ -65352,22 +65418,115 @@ function registerMemoryAuditTools(server) {
 // src/mcp/tools/memory-io.ts
 init_zod();
 init_memories();
+init_redact();
+
+// src/mcp/tools/bounded-output.ts
+var MCP_COMPACT_MAX_BYTES = 32 * 1024;
+var MCP_FULL_MAX_BYTES = 64 * 1024;
+var MCP_EXPLICIT_MAX_BYTES = 1024 * 1024;
+function mcpMaxBytes(value, detail) {
+  if (value === undefined)
+    return detail === "full" ? MCP_FULL_MAX_BYTES : MCP_COMPACT_MAX_BYTES;
+  const parsed = typeof value === "number" ? value : Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1024 || parsed > MCP_EXPLICIT_MAX_BYTES) {
+    throw new Error(`max_bytes must be an integer from 1024 to ${MCP_EXPLICIT_MAX_BYTES}`);
+  }
+  return parsed;
+}
+function boundedMcpOutput(args) {
+  const makeEnvelope = (items, byteTruncated, omitted) => {
+    const hasMore = byteTruncated || args.sourceHasMore;
+    const nextOffset = hasMore ? args.offset + items.length : null;
+    const envelope = {
+      [args.collection]: items,
+      _meta: {
+        receipt: args.receipt,
+        count: items.length,
+        limit: args.limit,
+        offset: args.offset,
+        next_offset: nextOffset,
+        has_more: hasMore,
+        complete: args.offset === 0 && !hasMore,
+        detail: args.detail,
+        max_bytes: args.maxBytes,
+        response_bytes: 0,
+        truncated: hasMore,
+        truncation_reason: byteTruncated ? "max_bytes" : args.sourceHasMore ? "limit" : null,
+        omitted_from_page: omitted,
+        next_arguments: nextOffset === null ? null : {
+          offset: nextOffset,
+          limit: args.limit,
+          ...args.includeDetailInNextArguments !== false && args.detail === "full" ? { detail: "full" } : {},
+          max_bytes: args.maxBytes,
+          ...args.nextArguments
+        },
+        continuation_scope: "unchanged_snapshot",
+        ...args.metadata
+      }
+    };
+    for (let attempt = 0;attempt < 8; attempt += 1) {
+      const bytes = Buffer.byteLength(JSON.stringify(envelope));
+      const meta = envelope["_meta"];
+      if (meta["response_bytes"] === bytes)
+        break;
+      meta["response_bytes"] = bytes;
+    }
+    return envelope;
+  };
+  for (let count = args.items.length;count >= 0; count -= 1) {
+    const byteTruncated = count < args.items.length;
+    const envelope = makeEnvelope(args.items.slice(0, count), byteTruncated, args.items.length - count);
+    const text = JSON.stringify(envelope);
+    if (Buffer.byteLength(text) > args.maxBytes)
+      continue;
+    if (count === 0 && args.items.length > 0) {
+      throw new Error(`One ${args.detail} result exceeds max_bytes=${args.maxBytes}; request compact detail or a larger max_bytes value`);
+    }
+    const meta = envelope["_meta"];
+    return {
+      text,
+      selectedCount: count,
+      hasMore: meta["has_more"] === true,
+      nextOffset: typeof meta["next_offset"] === "number" ? meta["next_offset"] : null
+    };
+  }
+  throw new Error(`Response metadata exceeds max_bytes=${args.maxBytes}`);
+}
+
+// src/mcp/tools/memory-io.ts
 function registerMemoryIoTools(server) {
-  server.tool("memory_export", "Export memories. format='json' (default) returns JSON array. format='v1' returns mementos-export-v1 JSONL with entity links.", {
+  server.tool("memory_export", "Export one truthful byte-bounded page. format='json' returns full memory objects; format='v1' returns portable entries with entity links. Continue with next_offset.", {
     scope: exports_external.enum(["global", "shared", "private", "working"]).optional(),
     category: exports_external.enum(["preference", "fact", "knowledge", "history", "procedural", "resource"]).optional(),
     agent_id: exports_external.string().optional(),
     project_id: exports_external.string().optional(),
-    format: exports_external.enum(["json", "v1"]).optional().describe("Export format: json (default) or v1 (JSONL with entity links)")
+    format: exports_external.enum(["json", "v1"]).optional().describe("Export page format: json (default) or portable v1 entries"),
+    limit: exports_external.coerce.number().int().min(1).max(1000).optional().describe("Page size (default: 20, maximum: 1000)"),
+    offset: exports_external.coerce.number().int().min(0).optional().describe("Continuation offset"),
+    max_bytes: exports_external.coerce.number().int().min(1024).max(1024 * 1024).optional().describe("Response ceiling (default: 65536, maximum: 1048576)")
   }, async (args) => {
     try {
-      if (args.format === "v1") {
-        const { exportV1: exportV12, toJsonl: toJsonl2 } = await Promise.resolve().then(() => (init_export_v1(), exports_export_v1));
-        const entries = exportV12({ ...args });
-        return { content: [{ type: "text", text: toJsonl2(entries) }] };
-      }
-      const memories = listMemoriesBounded({ ...args }, 1e4).rows;
-      return { content: [{ type: "text", text: JSON.stringify(memories, null, 2) }] };
+      const { format, limit: requestedLimit, offset: requestedOffset, max_bytes, ...filter } = args;
+      const limit = requestedLimit ?? 20;
+      const offset = requestedOffset ?? 0;
+      const page = listMemoriesBounded({ ...filter, offset }, limit);
+      const memories = page.rows.map(redactMemoryForOutput);
+      const portable = format === "v1";
+      const items = portable ? (await Promise.resolve().then(() => (init_export_v1(), exports_export_v1))).exportV1Entries(memories) : memories;
+      const output = boundedMcpOutput({
+        collection: portable ? "entries" : "memories",
+        receipt: portable ? "mementos.export.v1.page.v1" : "mementos.export.page.v1",
+        items,
+        offset,
+        limit,
+        sourceHasMore: page.has_more,
+        detail: "full",
+        maxBytes: mcpMaxBytes(max_bytes, "full"),
+        metadata: { format: portable ? "v1" : "json" },
+        nextArguments: { format: portable ? "v1" : "json", ...filter },
+        includeDetailInNextArguments: false
+      });
+      return { content: [{ type: "text", text: output.text }] };
     } catch (e) {
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
@@ -65473,7 +65632,7 @@ function getSubscriptionNotifications(agentId, db) {
 init_hooks();
 init_machine_visibility();
 function registerMemoryInjectTools(server) {
-  server.tool("memory_inject", "Get memory context for system prompt injection. Selects by scope, importance, recency. Use strategy='smart' with a query for embedding-based relevance scoring.", {
+  server.tool("memory_inject", "Get memory context for system prompt injection. Defaults to lightweight hints; set mode='full' explicitly for complete content.", {
     agent_id: exports_external.string().optional(),
     project_id: exports_external.string().optional(),
     session_id: exports_external.string().optional(),
@@ -65485,11 +65644,12 @@ function registerMemoryInjectTools(server) {
     strategy: exports_external.enum(["default", "smart"]).optional().describe("Injection strategy: 'default' uses importance+recency, 'smart' uses embedding similarity+importance+recency"),
     query: exports_external.string().optional().describe("Query for smart injection relevance scoring. Required when strategy='smart'."),
     task_context: exports_external.string().optional().describe("What the agent is about to do. When provided, activates intent-based retrieval \u2014 matches against when_to_use fields for situationally relevant memories."),
-    mode: exports_external.enum(["full", "hints"]).optional().default("full").describe("'full' = inject complete memory content (default), 'hints' = inject lightweight topic summary with counts, saving 60-70% tokens. Agent uses memory_recall to pull details as needed."),
+    mode: exports_external.enum(["full", "hints"]).optional().default("hints").describe("'hints' = lightweight topic summary (default); 'full' = explicit complete content compatibility."),
     machine_id: exports_external.string().optional().describe("Current machine ID for machine-local memory visibility. Defaults to the current machine.")
   }, async (args) => {
     try {
-      if (args.strategy === "smart" && args.task_context && args.mode !== "hints") {
+      const mode = args.mode ?? "hints";
+      if (args.strategy === "smart" && args.task_context && mode !== "hints") {
         const { smartInject: smartInject2 } = await Promise.resolve().then(() => (init_injector(), exports_injector));
         const result = await smartInject2({
           task_context: args.task_context,
@@ -65620,7 +65780,7 @@ function registerMemoryInjectTools(server) {
           return new Date(b.updated_at).getTime() - new Date(a.updated_at).getTime();
         });
       }
-      if (args.mode === "hints") {
+      if (mode === "hints") {
         let extractTopics = function(memories, maxTopics = 8) {
           const wordCounts = new Map;
           for (const m of memories) {
@@ -66956,6 +67116,7 @@ function checkMemoryWriteLock(key, scope, projectId, db) {
 
 // src/mcp/tools/lock-tools.ts
 init_api_mode();
+init_conversations_transport();
 function formatLockLine(lock, index) {
   return `${index + 1}. ${lock.id.slice(0, 8)} ${lock.lock_type} ${lock.resource_type}:${compactText(lock.resource_id, 48)} agent=${lock.agent_id} expires=${lock.expires_at}`;
 }
@@ -67111,15 +67272,16 @@ ${visible.map(formatLockLine).join(`
     const expired = cleanExpiredLocksWithInfo();
     const count = expired.length;
     if (count > 0) {
-      const conversationsUrl = process.env.CONVERSATIONS_API_URL || "http://localhost:7020";
       for (const lock of expired) {
         const msg = `Your ${lock.lock_type} lock on ${lock.resource_type}/${lock.resource_id} has expired. Another agent may now acquire it.`;
-        fetch(`${conversationsUrl}/api/v1/messages`, {
+        conversationsRequest("/messages", {
           method: "POST",
           headers: { "Content-Type": "application/json" },
           body: JSON.stringify({ from: "system", to: lock.agent_id, content: msg }),
           signal: AbortSignal.timeout(2000)
-        }).catch(() => {});
+        }).catch(() => {
+          return;
+        });
       }
     }
     return { content: [{ type: "text", text: `Cleaned ${count} expired lock(s)${count > 0 ? ` and notified ${count} agent(s)` : ""}.` }] };
@@ -69506,7 +69668,10 @@ var UTILITY_TOOL_SCHEMAS = {
       agent_id: { type: "string", description: "Agent UUID filter" },
       project_id: { type: "string", description: "Project UUID filter" },
       scope: { type: "string", description: "Scope filter", enum: ["global", "shared", "private", "working"] },
-      limit: { type: "number", description: "Max results (default: 30)" },
+      limit: { type: "number", description: "Max results (default: 10, maximum: 50)" },
+      offset: { type: "number", description: "Continuation offset in the ranked result set" },
+      detail: { type: "string", description: "compact previews (default) or explicit full memory objects", enum: ["compact", "full"] },
+      max_bytes: { type: "number", description: "Response byte ceiling (compact default: 32768; full default: 65536)" },
       decay_halflife_days: { type: "number", description: "Importance half-life in days (default: 90). Lower = more weight on recent memories." },
       no_decay: { type: "boolean", description: "Set true to disable decay and sort purely by importance." },
       task_context: { type: "string", description: "What the agent is about to do. When provided, activates intent-based retrieval \u2014 matches against when_to_use fields." },
@@ -69630,15 +69795,18 @@ Summary: ${newMems.length} new, ${updatedMems.length} updated, ${expiredMems.len
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }
   });
-  server.tool("memory_context", "Get memories relevant to current context. Uses time-weighted scoring: score = importance \xD7 decay(age). Pinned memories are exempt. Returns effective_score on each memory.", {
+  server.tool("memory_context", "Get a ranked, byte-bounded memory-context page. Compact detail is the default; set detail='full' explicitly for complete memory fields.", {
     agent_id: exports_external.string().optional(),
     project_id: exports_external.string().optional(),
     scope: exports_external.enum(["global", "shared", "private", "working"]).optional(),
-    limit: exports_external.coerce.number().optional(),
+    limit: exports_external.coerce.number().optional().describe("Max results (default: 10, maximum: 50)"),
+    offset: exports_external.coerce.number().int().min(0).optional().describe("Continuation offset in the ranked result set"),
+    detail: exports_external.enum(["compact", "full"]).optional().default("compact").describe("compact returns ~240-character previews; full returns complete memory objects"),
+    max_bytes: exports_external.coerce.number().int().min(1024).max(1024 * 1024).optional().describe("Response ceiling (compact default: 32768; full default: 65536)"),
     decay_halflife_days: exports_external.coerce.number().optional().describe("Importance half-life in days (default: 90). Lower = more weight on recent memories."),
     no_decay: exports_external.coerce.boolean().optional().describe("Set true to disable decay and sort purely by importance."),
-    task_context: exports_external.string().optional().describe("What the agent is about to do. When provided, activates intent-based retrieval \u2014 matches against when_to_use fields for situationally relevant memories."),
-    strategy: exports_external.enum(["default", "smart"]).optional().default("default").describe("Injection strategy: 'default' = decay-scored, 'smart' = activation-matched + layered + tool-aware (requires task_context)"),
+    task_context: exports_external.string().optional().describe("What the agent is about to do. When provided, activates intent-based retrieval \u2014 matches against when_to_use fields."),
+    strategy: exports_external.enum(["default", "smart"]).optional().default("default").describe("'default' = ranked bounded page, 'smart' = activation-matched pipeline when task_context is provided"),
     machine_id: exports_external.string().optional().describe("Current machine ID for machine-local memory visibility. Defaults to the current machine.")
   }, async (args) => {
     try {
@@ -69653,16 +69821,18 @@ Summary: ${newMems.length} new, ${updatedMems.length} updated, ${expiredMems.len
         });
         return { content: [{ type: "text", text: result.output }] };
       }
+      const limit = positiveLimit(args.limit, 10);
+      const offset = args.offset ?? 0;
+      const detail = args.detail ?? "compact";
       const visibleMachineId = resolveVisibleMachineId(args.machine_id);
       const filter = {
         scope: args.scope,
         agent_id: args.agent_id,
         project_id: args.project_id,
         status: "active",
-        visible_to_machine_id: visibleMachineId,
-        limit: (args.limit || 30) * 2
+        visible_to_machine_id: visibleMachineId
       };
-      const memories = listMemories(filter);
+      const memories = listMemoriesBounded(filter, undefined).rows;
       const activationBoostedIds = new Set;
       if (args.task_context) {
         try {
@@ -69674,45 +69844,80 @@ Summary: ${newMems.length} new, ${updatedMems.length} updated, ${expiredMems.len
             agent_id: args.agent_id,
             project_id: args.project_id
           });
-          const seenIds = new Set(memories.map((m) => m.id));
-          for (const r of activationResults) {
-            if (!isMemoryVisibleToMachine(r.memory, visibleMachineId))
+          const seenIds = new Set(memories.map((memory) => memory.id));
+          for (const result of activationResults) {
+            if (!isMemoryVisibleToMachine(result.memory, visibleMachineId))
               continue;
-            activationBoostedIds.add(r.memory.id);
-            if (!seenIds.has(r.memory.id)) {
-              seenIds.add(r.memory.id);
-              memories.push(r.memory);
+            activationBoostedIds.add(result.memory.id);
+            if (!seenIds.has(result.memory.id)) {
+              seenIds.add(result.memory.id);
+              memories.push(result.memory);
             }
           }
         } catch {}
       }
-      if (memories.length === 0) {
-        return { content: [{ type: "text", text: "No memories in current context." }] };
-      }
       const halflifeDays = args.decay_halflife_days ?? 90;
       const now3 = Date.now();
-      const scored = memories.map((m) => {
-        const activationBoost = activationBoostedIds.has(m.id) ? 3 : 0;
-        let effectiveScore = m.importance + activationBoost;
-        if (!args.no_decay && !m.pinned) {
-          const ageMs = now3 - new Date(m.updated_at).getTime();
-          const ageDays = ageMs / 86400000;
-          const decayFactor = Math.pow(0.5, ageDays / halflifeDays);
-          effectiveScore = (m.importance + activationBoost) * decayFactor;
-        }
-        if (m.flag)
+      const scored = memories.map((memory) => {
+        const activationBoost = activationBoostedIds.has(memory.id) ? 3 : 0;
+        let effectiveScore = memory.importance + activationBoost;
+        if (!args.no_decay && !memory.pinned) {
+          const ageDays = (now3 - new Date(memory.updated_at).getTime()) / 86400000;
+          effectiveScore *= Math.pow(0.5, ageDays / halflifeDays);
+        }
+        if (memory.flag)
           effectiveScore = Math.max(effectiveScore, 11);
-        return { ...m, effective_score: Math.round(effectiveScore * 100) / 100 };
+        return {
+          ...memory,
+          effective_score: Math.round(effectiveScore * 100) / 100,
+          activation_matched: activationBoostedIds.has(memory.id)
+        };
       });
-      const limit = args.limit || 30;
-      scored.sort((a, b) => b.effective_score - a.effective_score);
-      const top = scored.slice(0, limit);
-      for (const m of top) {
-        touchMemory(m.id);
-      }
-      const lines = top.map((m) => `[${m.scope}/${m.category}] ${m.key}: ${m.value} (score: ${m.effective_score}, raw: ${m.importance}${m.pinned ? ", pinned" : ""}${m.flag ? `, flag: ${m.flag}` : ""})`);
-      return { content: [{ type: "text", text: lines.join(`
-`) }] };
+      scored.sort((a, b) => b.effective_score - a.effective_score || b.importance - a.importance || new Date(b.updated_at).getTime() - new Date(a.updated_at).getTime() || b.id.localeCompare(a.id));
+      const page = scored.slice(offset, offset + limit + 1);
+      const hasMore = page.length > limit;
+      const visible = hasMore ? page.slice(0, limit) : page;
+      const items = detail === "full" ? visible : visible.map((memory) => ({
+        id: memory.id,
+        key: memory.key,
+        preview: compactText(memory.summary || memory.value, 240),
+        scope: memory.scope,
+        category: memory.category,
+        importance: memory.importance,
+        effective_score: memory.effective_score,
+        pinned: memory.pinned,
+        ...memory.flag ? { flag: memory.flag } : {},
+        ...memory.activation_matched ? { activation_matched: true } : {},
+        updated_at: memory.updated_at
+      }));
+      const output = boundedMcpOutput({
+        collection: "memories",
+        receipt: "mementos.context.page.v1",
+        items,
+        offset,
+        limit,
+        sourceHasMore: hasMore,
+        detail,
+        maxBytes: mcpMaxBytes(args.max_bytes, detail),
+        metadata: {
+          total_ranked: scored.length,
+          ranking: {
+            order: "effective_score_desc,importance_desc,updated_at_desc,id_desc",
+            decay_halflife_days: halflifeDays,
+            decay_enabled: !args.no_decay,
+            activation_boost: 3,
+            flagged_score_floor: 11
+          }
+        },
+        nextArguments: {
+          ...args.scope ? { scope: args.scope } : {},
+          ...args.agent_id ? { agent_id: args.agent_id } : {},
+          ...args.project_id ? { project_id: args.project_id } : {}
+        }
+      });
+      for (const memory of visible.slice(0, output.selectedCount))
+        touchMemory(memory.id);
+      return { content: [{ type: "text", text: output.text }] };
     } catch (e) {
       return { content: [{ type: "text", text: formatError(e) }], isError: true };
     }

package/dist/mcp/memory-broadcast.d.ts

@@ -1,12 +1,10 @@
 /**
  * Memory broadcast utility — notifies active agents when shared memories are saved.
- * Uses the conversations MCP service if available.
- * Non-blocking: failures are silently ignored.
+ * Conversations authority and credentials resolve through @hasna/contracts.
+ * Non-blocking: notification failures never fail the memory write.
  */
-import type { Memory } from '../types/index.js';
-/**
- * Broadcast a newly saved shared memory to all active agents on the project
- * via the conversations MCP send_message endpoint.
- */
-export declare function broadcastSharedMemory(memory: Memory, savingAgentId: string): Promise<void>;
+import type { Memory } from "../types/index.js";
+import { type ConversationsTransportOptions } from "../lib/conversations-transport.js";
+/** Broadcast a newly saved shared memory to the other active project agents. */
+export declare function broadcastSharedMemory(memory: Memory, savingAgentId: string, transport?: ConversationsTransportOptions): Promise<void>;
 //# sourceMappingURL=memory-broadcast.d.ts.map

package/dist/mcp/memory-broadcast.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory-broadcast.d.ts","sourceRoot":"","sources":["../../src/mcp/memory-broadcast.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAIhD;;;GAGG;AACH,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA4BhG"}
+{"version":3,"file":"memory-broadcast.d.ts","sourceRoot":"","sources":["../../src/mcp/memory-broadcast.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAEL,KAAK,6BAA6B,EACnC,MAAM,mCAAmC,CAAC;AAE3C,gFAAgF;AAChF,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,EACrB,SAAS,GAAE,6BAAkC,GAC5C,OAAO,CAAC,IAAI,CAAC,CA8Bf"}