@pyxmate/memory 0.24.0 → 0.26.0

package/README.md

@@ -36,6 +36,15 @@ Restart Claude Code. The 7 memory tools (`search_memories`, `store_memory`,
 `get_memory`, `list_memories`, `delete_memory`, `ingest_memory_file`,
 `summarize_memory_entity`) are auto-discovered via MCP Tool Search.
 
+**That's the whole setup** — no extra LLM API keys. When the agent calls
+`store_memory` without supplying `entities`/`relationships`, the MCP tool
+auto-extracts a graph topology by asking the agent's own LLM via MCP sampling
+(same pattern as image-description / `extractEntitiesV2` for file ingest).
+Your LLM, your credentials. Pass `extractEntities: false` on a per-call basis
+to opt out of auto-extraction. See
+[`graph-auto-entity-extraction-v2`](https://github.com/pyx-corp/pyx-memory-v1/blob/main/docs/specs/graph-auto-entity-extraction-v2/spec.md)
+for the full contract.
+
 Drop the [agent-template snippet](https://github.com/pyx-corp/pyx-memory-v1/blob/main/docs/agent-template.md)
 into your project's `CLAUDE.md` / `AGENTS.md` to tell the agent WHEN to search
 vs store.
@@ -59,6 +68,36 @@ await memory.store({
 const results = await memory.search({ query: 'deadline', limit: 5 });
 ```
 
+### Optional: client-side auto-extraction
+
+`MemoryClient.store(entry, options)` accepts an `enrichment.extractEntities`
+callback. The SDK invokes your callback (running against **your own** LLM
+credentials), merges the result with any caller-supplied entities using
+case-insensitive caller-wins, and sends the populated graph data to the server.
+Mirrors the existing file-ingest `extractEntitiesV2` pattern.
+
+```ts
+await memory.store(
+  { content: 'Andrej Karpathy joined OpenAI as a co-founder in late 2015.',
+    metadata: { topic: 'history', project: 'orca' } },
+  {
+    enrichment: {
+      extractEntities: async ({ content, signal }) => {
+        // Call YOUR LLM here. Return { entities, relations } matching the
+        // EntityType/RelationType vocabularies. Throw on parse failures —
+        // errors propagate to the caller, no silent swallow.
+        return { entities: [...], relations: [...] };
+      },
+    },
+    signal, // AbortSignal forwarded into both the callback and the fetch
+  },
+);
+```
+
+Per-call `entry.extractEntities: false` skips the callback entirely;
+`entry.extractEntities: true` with no callback throws a loud error (no silent
+no-op). The server never sees an LLM API key — it just persists what you send.
+
 ## Entry Points
 
 | Import | What you get |

package/dist/{chunk-4DRKAXJE.mjs → chunk-47O2JYAP.mjs}

@@ -1,6 +1,6 @@
 import {
   MemoryClient
-} from "./chunk-D5PMQYZM.mjs";
+} from "./chunk-N6IRAUXH.mjs";
 
 // ../dashboard/src/aggregations/consolidation-analytics.ts
 function analyzeConsolidationLog(entries) {

package/dist/{chunk-D5PMQYZM.mjs → chunk-N6IRAUXH.mjs}

@@ -1,4 +1,7 @@
 // ../client/src/memory-client.ts
+import {
+  mergeExtractedEntities
+} from "@pyx-memory/shared";
 var MemoryServerError = class extends Error {
   status;
   constructor(message, status) {
@@ -50,10 +53,34 @@ var MemoryClient = class {
       throw new Error(`Memory server not reachable at ${this.baseUrl}: ${response.status}`);
     }
   }
-  async store(entry) {
+  async store(entry, options) {
+    const callback = options?.enrichment?.extractEntities;
+    const optedOut = entry.extractEntities === false;
+    const wantsForced = entry.extractEntities === true;
+    if (wantsForced && !callback) {
+      throw new Error(
+        "extractEntities=true requested but no enrichment.extractEntities callback was provided. Pass options.enrichment.extractEntities, or set entry.extractEntities=false to skip."
+      );
+    }
+    let payload = entry;
+    if (callback && !optedOut) {
+      const extracted = await callback({
+        content: entry.content,
+        ...entry.metadata ? { metadata: entry.metadata } : {},
+        ...options?.signal ? { signal: options.signal } : {}
+      });
+      const merged = mergeExtractedEntities(entry.entities, entry.relationships, extracted);
+      const { extractEntities: _drop, ...rest } = entry;
+      payload = {
+        ...rest,
+        entities: merged.entities,
+        relationships: merged.relationships
+      };
+    }
     return this.fetchApi("/api/memory/ingest", {
       method: "POST",
-      body: JSON.stringify(entry)
+      body: JSON.stringify(payload),
+      ...options?.signal ? { signal: options.signal } : {}
     });
   }
   async search(params) {
@@ -101,6 +128,18 @@ var MemoryClient = class {
     const stats = await this.fetchApi("/api/memory/stats");
     return { ...stats, connected: true };
   }
+  /**
+   * Fetch the running server's topology snapshot (build variant, declared
+   * role, embedding location, active model profile). Round-trips the
+   * server's `GET /status` envelope through {@link fetchApi}, surfacing any
+   * non-success response as {@link MemoryServerError}. Auth-header
+   * forwarding is unchanged from other client methods even though `/status`
+   * is server-side public — the server simply ignores credentials on that
+   * route.
+   */
+  async status() {
+    return this.fetchApi("/status");
+  }
   async shutdown() {
   }
   async list(params = {}) {
@@ -109,6 +148,9 @@ var MemoryClient = class {
     if (params.limit != null) searchParams.set("limit", String(params.limit));
     if (params.type) searchParams.set("type", params.type);
     if (params.agentId) searchParams.set("agentId", params.agentId);
+    if (params.includeKinds && params.includeKinds.length > 0) {
+      searchParams.set("includeKinds", params.includeKinds.join(","));
+    }
     const qs = searchParams.toString();
     return this.fetchApi(`/api/memory/entries${qs ? `?${qs}` : ""}`);
   }

package/dist/cli/pyx-mem.mjs

@@ -517,6 +517,44 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 // src/mcp/instructions.ts
 var PYX_MEMORY_INSTRUCTIONS = `Use pyx-memory to search durable project/user memory before assuming prior decisions, and to store concise facts after corrections, bug fixes, design decisions, integration discoveries, gotchas, explicit preferences, or "remember this" requests. Store decisions, not deliberation. Include topic and project. Add entities/relationships for named people, tools, organizations, locations, or events. Use file ingest for documents/images worth persisting; images require a description.`;
 
+// src/mcp/sampling.ts
+function createSamplingClient(server) {
+  function isAvailable() {
+    const caps = server.server.getClientCapabilities();
+    return Boolean(caps?.sampling);
+  }
+  return {
+    isAvailable,
+    async complete(prompt, opts) {
+      if (!isAvailable()) {
+        throw new Error(
+          "MCP sampling unavailable: the connected client did not advertise the `sampling` capability. Either supply entities/relationships explicitly or set extractEntities:false on the request."
+        );
+      }
+      const result = await server.server.createMessage(
+        {
+          messages: [{ role: "user", content: { type: "text", text: prompt } }],
+          maxTokens: opts?.maxTokens ?? 2048
+        },
+        opts?.signal ? { signal: opts.signal } : void 0
+      );
+      const content = result.content;
+      if (content && typeof content === "object" && !Array.isArray(content)) {
+        const block = content;
+        if (block.type === "text" && typeof block.text === "string") return block.text;
+      }
+      if (Array.isArray(content)) {
+        for (const block of content) {
+          if (block && typeof block === "object" && block.type === "text" && typeof block.text === "string") {
+            return block.text;
+          }
+        }
+      }
+      throw new Error("MCP sampling returned no text content");
+    }
+  };
+}
+
 // ../../node_modules/zod/v4/classic/external.js
 var external_exports = {};
 __export(external_exports, {
@@ -15343,6 +15381,83 @@ var searchMemoriesTool = {
   }
 };
 
+// src/mcp/tools/status.ts
+var inputShape6 = {};
+var statusTool = {
+  name: "status",
+  config: {
+    title: "Get pyx-memory topology",
+    description: "Fetch the running pyx-memory server topology: build variant (cloud|full), declared deployment role, server version, embedding location (inline|remote), and active model profile. HTTP proxy to GET /status \u2014 no in-process branch.",
+    inputSchema: inputShape6,
+    annotations: { readOnlyHint: true, openWorldHint: true }
+  },
+  handler: (deps) => async () => {
+    const creds = await deps.readCredentials();
+    if (!creds.ok) return creds.result;
+    const http = createHttpClient(creds.credentials, deps.fetchImpl);
+    const res = await http.requestJson({ method: "GET", path: "/status" });
+    return res.ok ? mcpJson(res.data) : res.result;
+  }
+};
+
+// src/mcp/tools/store.ts
+import { mergeExtractedEntities } from "@pyx-memory/shared";
+
+// src/mcp/extraction-prompt.ts
+var ENTITY_TYPES = ["PERSON", "ORGANIZATION", "CONCEPT", "TOOL", "LOCATION", "EVENT"];
+var RELATION_TYPES = [
+  "USES",
+  "OWNS",
+  "DEPENDS_ON",
+  "RELATED_TO",
+  "CREATED_BY",
+  "PART_OF",
+  "IS_A",
+  "WORKS_AT",
+  "LOCATED_IN"
+];
+var ExtractionSchema = external_exports.object({
+  entities: external_exports.array(
+    external_exports.object({
+      name: external_exports.string().min(1),
+      type: external_exports.enum(ENTITY_TYPES)
+    })
+  ),
+  relations: external_exports.array(
+    external_exports.object({
+      source: external_exports.string().min(1),
+      target: external_exports.string().min(1),
+      type: external_exports.enum(RELATION_TYPES)
+    })
+  )
+});
+function buildExtractionPrompt(content) {
+  return [
+    "Extract graph facts as JSON only. No prose, no fences, no commentary.",
+    `Schema: {"entities":[{"name":string,"type":EntityType}],"relations":[{"source":string,"target":string,"type":RelationType}]}.`,
+    `EntityType values: ${ENTITY_TYPES.join(", ")}.`,
+    `RelationType values: ${RELATION_TYPES.join(", ")}.`,
+    "Include only entities/relations explicitly named or strongly implied in the content. Empty arrays are valid.",
+    `Content: ${content}`
+  ].join("\n");
+}
+function parseExtractionResponse(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (cause) {
+    throw new Error(
+      `MCP sampling returned non-JSON text (first 120 chars: ${raw.slice(0, 120).replace(/\n/g, "\\n")})`,
+      { cause: cause instanceof Error ? cause : void 0 }
+    );
+  }
+  const result = ExtractionSchema.safeParse(parsed);
+  if (!result.success) {
+    throw new Error(`MCP sampling response failed schema validation: ${result.error.message}`);
+  }
+  return result.data;
+}
+
 // src/mcp/tools/store.ts
 var entityTypes = ["PERSON", "ORGANIZATION", "CONCEPT", "TOOL", "LOCATION", "EVENT"];
 var relationshipTypes = [
@@ -15356,7 +15471,7 @@ var relationshipTypes = [
   "WORKS_AT",
   "LOCATED_IN"
 ];
-var inputShape6 = {
+var inputShape7 = {
   content: external_exports.string().min(1).describe("Concise factual statement to persist; decision, not deliberation."),
   topic: external_exports.string().min(1).describe("Required metadata.topic for retrieval grouping."),
   project: external_exports.string().min(1).describe("Required metadata.project namespace."),
@@ -15372,29 +15487,57 @@ var inputShape6 = {
       name: external_exports.string().min(1).describe("Entity name as referenced in content."),
       type: external_exports.enum(entityTypes).describe("Entity type.")
     })
-  ).optional().describe("Named entities mentioned by the content; required when relationships are present."),
+  ).optional().describe(
+    "Named entities mentioned by the content; required when relationships are present. When omitted, the MCP tool may auto-extract via the connected client's LLM (MCP sampling) before sending to the server; set `extractEntities:false` to skip."
+  ),
   relationships: external_exports.array(
     external_exports.object({
       source: external_exports.string().min(1).describe("Source entity name (must appear in entities array)."),
       target: external_exports.string().min(1).describe("Target entity name (must appear in entities array)."),
       type: external_exports.enum(relationshipTypes).describe("Relationship type.")
     })
-  ).optional().describe("Edges between entities; source and target must be entity names from this request."),
+  ).optional().describe(
+    "Edges between entities; source and target must be entity names from this request. When omitted, the MCP tool may auto-extract via the connected client's LLM (MCP sampling) before sending to the server; set `extractEntities:false` to skip."
+  ),
+  extractEntities: external_exports.boolean().optional().describe(
+    "Override client-side auto-extraction (MCP sampling): false to skip, true to require (errors if the connected client does not support sampling)."
+  ),
   ...scopeShape
 };
 var storeMemoryTool = {
   name: "store_memory",
   config: {
     title: "Store pyx-memory entry",
-    description: "Store one concise factual memory with required topic and project metadata. Provide entities/relationships when content names people, tools, orgs, locations, or events.",
-    inputSchema: inputShape6,
+    description: "Store one concise factual memory with required topic and project metadata. Provide entities/relationships explicitly when you want exact graph topology; when omitted, the MCP tool may auto-extract using your own LLM via MCP sampling before sending to the server.",
+    inputSchema: inputShape7,
     annotations: { readOnlyHint: false, idempotentHint: false, openWorldHint: true }
   },
-  handler: (deps) => async (raw) => {
+  handler: (deps) => async (raw, ctx) => {
     const args = raw;
     const creds = await deps.readCredentials();
     if (!creds.ok) return creds.result;
     const http = createHttpClient(creds.credentials, deps.fetchImpl);
+    let entities = args.entities;
+    let relationships = args.relationships;
+    const samplingAvailable = deps.samplingClient?.isAvailable() ?? false;
+    const optedOut = args.extractEntities === false;
+    const forced = args.extractEntities === true;
+    if (forced && !samplingAvailable) {
+      throw new Error(
+        "extractEntities=true requested but the connected MCP client did not advertise the `sampling` capability. Pass entities/relationships explicitly, set extractEntities:false, or connect a sampling-capable client."
+      );
+    }
+    if (deps.samplingClient && samplingAvailable && !optedOut && (entities?.length ?? 0) === 0) {
+      const prompt = buildExtractionPrompt(args.content);
+      const completion = await deps.samplingClient.complete(
+        prompt,
+        ctx?.signal ? { signal: ctx.signal } : void 0
+      );
+      const extracted = parseExtractionResponse(completion);
+      const merged = mergeExtractedEntities(args.entities, args.relationships, extracted);
+      entities = merged.entities;
+      relationships = merged.relationships;
+    }
     const body = {
       content: args.content,
       type: args.type ?? "long-term",
@@ -15408,8 +15551,8 @@ var storeMemoryTool = {
       agentId: args.agentId,
       sessionId: args.sessionId,
       parentId: args.parentId,
-      entities: args.entities,
-      relationships: args.relationships
+      entities,
+      relationships
     };
     const res = await http.requestJson({
       method: "POST",
@@ -15422,7 +15565,7 @@ var storeMemoryTool = {
 };
 
 // src/mcp/tools/summarize.ts
-var inputShape7 = {
+var inputShape8 = {
   entityName: external_exports.string().min(1).describe(
     "Entity name to synthesize a profile for (PERSON, ORG, CONCEPT, TOOL, LOCATION, EVENT)."
   ),
@@ -15437,7 +15580,7 @@ var summarizeMemoryEntityTool = {
   config: {
     title: "Synthesize pyx-memory entity",
     description: "Fetch or refresh a reusable synthesis/profile for an entity (person, customer, project, tool, organization). Default fetches existing; set refresh:true to rebuild.",
-    inputSchema: inputShape7,
+    inputSchema: inputShape8,
     annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: true }
   },
   handler: (deps) => async (raw) => {
@@ -15472,24 +15615,30 @@ var ALL_TOOLS = [
   listMemoriesTool,
   deleteMemoryTool,
   ingestMemoryFileTool,
-  summarizeMemoryEntityTool
+  summarizeMemoryEntityTool,
+  statusTool
 ];
 var ALL_TOOL_NAMES = ALL_TOOLS.map((t) => t.name);
 
 // src/mcp/server.ts
 async function runMcpServer(opts) {
   const fetchImpl = opts.fetchImpl ?? fetch;
-  const version2 = opts.version ?? (true ? "0.24.0" : "0.0.0-dev");
+  const version2 = opts.version ?? (true ? "0.26.0" : "0.0.0-dev");
   const server = new McpServer(
     { name: "pyx-memory", version: version2 },
     { instructions: PYX_MEMORY_INSTRUCTIONS, capabilities: { tools: {} } }
   );
+  const samplingClient = createSamplingClient(server);
   for (const tool of ALL_TOOLS) {
-    const handle = tool.handler({ readCredentials: opts.readCredentials, fetchImpl });
+    const handle = tool.handler({
+      readCredentials: opts.readCredentials,
+      fetchImpl,
+      samplingClient
+    });
     server.registerTool(
       tool.name,
       tool.config,
-      async (args) => handle(args)
+      async (args, extra) => handle(args, { signal: extra?.signal })
     );
   }
   const transport = new StdioServerTransport();
@@ -15661,6 +15810,7 @@ function mcpInstallClaudeCodeCommand(opts = {}) {
   process.stdout.write(
     `Installed pyx-memory MCP server in Claude Code (scope: ${scope}).
 Restart Claude Code to make the tools available. No API key was written to .mcp.json \u2014 credentials live in the OS credential store.
+Graph entities/relationships auto-extract via your client's own LLM (MCP sampling) when you call store_memory without entities \u2014 no extra LLM keys to configure.
 `
   );
   return EXIT.OK;

package/dist/dashboard.mjs

@@ -11,8 +11,8 @@ import {
   toGraphologyFormat,
   transformGraphData,
   unreachableHealth
-} from "./chunk-4DRKAXJE.mjs";
-import "./chunk-D5PMQYZM.mjs";
+} from "./chunk-47O2JYAP.mjs";
+import "./chunk-N6IRAUXH.mjs";
 import "./chunk-7P6ASYW6.mjs";
 export {
   DashboardClient,

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { StoreInput as StoreInput$1, MemoryEntry as MemoryEntry$1, MemorySearchParams as MemorySearchParams$1, MemorySearchResult as MemorySearchResult$1, MemoryType as MemoryType$1, PrincipalContext as PrincipalContext$1, MemoryStats as MemoryStats$1, WikiLintReport as WikiLintReport$1, ExtractedImageMeta as ExtractedImageMeta$1, IngestEntity as IngestEntity$1, IngestRelationship as IngestRelationship$1, IngestEvent as IngestEvent$1, GraphNode as GraphNode$1, GraphTraversalResult as GraphTraversalResult$1 } from '@pyx-memory/shared';
+import { StoreInput as StoreInput$1, MemoryEntry as MemoryEntry$1, MemorySearchParams as MemorySearchParams$1, MemorySearchResult as MemorySearchResult$1, MemoryType as MemoryType$1, PrincipalContext as PrincipalContext$1, MemoryStats as MemoryStats$1, WikiLintReport as WikiLintReport$1, ExtractedImageMeta as ExtractedImageMeta$1, IngestEntity as IngestEntity$1, IngestRelationship as IngestRelationship$1, EntityExtractionResult as EntityExtractionResult$1, Topology as Topology$1, IngestEvent as IngestEvent$1, GraphNode as GraphNode$1, GraphTraversalResult as GraphTraversalResult$1 } from '@pyx-memory/shared';
 
 /** Parameters for paginated entry listing. */
 interface MemoryListParams {
@@ -19,6 +19,15 @@ interface MemoryListParams {
      * and get the legacy tenant-only scope.
      */
     principal?: PrincipalContext$1;
+    /**
+     * R1/R2 — opt-in list of `metadata._kind` values to include in the
+     * response. When omitted or empty, the default-set returns only entries
+     * with NO `_kind` system metadata (e.g. `_kind:'entity-summary'` rows
+     * are hidden). When supplied, the listed kinds are returned IN ADDITION
+     * to the default-set (additive, not replacement). See
+     * `docs/specs/topic-org-v025-f1-include-kinds/spec.md`.
+     */
+    includeKinds?: string[];
 }
 /** Result of a paginated entry listing. */
 interface MemoryListResult {
@@ -169,6 +178,35 @@ interface IngestFileOptions {
     signal?: AbortSignal;
     namespaceId?: string;
 }
+/**
+ * Caller-supplied enrichment for the per-call store path. Mirrors
+ * {@link EnrichmentCallbacks} for file ingest — the SDK invokes the callback
+ * (against the caller's own LLM credentials) and merges the result into the
+ * ingest payload before POSTing, so the server holds no LLM keys.
+ */
+interface StoreEnrichmentCallbacks {
+    /**
+     * Extract entities + relationships from `content`. The caller's LLM does
+     * the work; the SDK passes the result through {@link mergeExtractedEntities}
+     * (caller-wins, case-insensitive) before sending to the server.
+     *
+     * Skipped when `entry.extractEntities === false`. When
+     * `entry.extractEntities === true` but this callback is not supplied,
+     * `MemoryClient.store()` throws a loud error rather than silently no-op'ing
+     * (same shape as the in-process Memory.store() guard).
+     */
+    extractEntities?: (input: {
+        content: string;
+        metadata?: Record<string, unknown>;
+        signal?: AbortSignal;
+    }) => Promise<EntityExtractionResult$1>;
+}
+/** Options accepted by {@link MemoryClient.store}. */
+interface StoreOptions {
+    enrichment?: StoreEnrichmentCallbacks;
+    /** Propagated into the `extractEntities` callback and the underlying fetch. */
+    signal?: AbortSignal;
+}
 /** Error thrown by MemoryClient when the server returns a non-success response. */
 declare class MemoryServerError extends Error {
     readonly status: number;
@@ -205,12 +243,22 @@ declare class MemoryClient implements ExtendedMemoryInterface {
     /** Encode a path segment to prevent URL injection */
     private encodePathSegment;
     initialize(): Promise<void>;
-    store(entry: StoreInput$1): Promise<MemoryEntry$1>;
+    store(entry: StoreInput$1, options?: StoreOptions): Promise<MemoryEntry$1>;
     search(params: MemorySearchParams$1): Promise<MemorySearchResult$1>;
     get(id: string): Promise<MemoryEntry$1 | null>;
     delete(id: string): Promise<boolean>;
     clearSession(sessionId: string): Promise<number>;
     stats(): Promise<MemoryStats$1>;
+    /**
+     * Fetch the running server's topology snapshot (build variant, declared
+     * role, embedding location, active model profile). Round-trips the
+     * server's `GET /status` envelope through {@link fetchApi}, surfacing any
+     * non-success response as {@link MemoryServerError}. Auth-header
+     * forwarding is unchanged from other client methods even though `/status`
+     * is server-side public — the server simply ignores credentials on that
+     * route.
+     */
+    status(): Promise<Topology$1>;
     shutdown(): Promise<void>;
     list(params?: MemoryListParams): Promise<MemoryListResult>;
     /**
@@ -318,12 +366,6 @@ declare const DEFAULTS: {
     readonly MEMORY_SERVER_PORT: 7822;
 };
 
-interface ApiResponse<T> {
-    success: boolean;
-    data?: T;
-    error?: string;
-}
-
 /** ISO 8601 timestamp string */
 type Timestamp = string;
 /** Unique agent identifier */
@@ -538,6 +580,8 @@ type StoreInput = Omit<MemoryEntry, 'id' | 'createdAt'> & {
     entities?: IngestEntity[];
     /** Agent-provided relationships for graph storage. */
     relationships?: IngestRelationship[];
+    /** Override server-side auto-extraction for this store call. */
+    extractEntities?: boolean;
     /** Graph-failure handling. Default: "throw" (loud) — see GraphFailureMode. */
     graphFailureMode?: GraphFailureMode;
 };
@@ -553,6 +597,8 @@ interface MemoryIngestRequest {
     entities?: IngestEntity[];
     /** Agent-provided relationships for graph storage. */
     relationships?: IngestRelationship[];
+    /** Override server-side auto-extraction for this ingest request. */
+    extractEntities?: boolean;
     /** Graph-failure handling. Default: "throw" (loud) — see GraphFailureMode. */
     graphFailureMode?: GraphFailureMode;
     /** Importance score (1-10). */
@@ -642,6 +688,89 @@ interface WikiLintReport {
     }>;
 }
 
+/**
+ * Result shape returned by an LLM entity extractor — entities + relations.
+ *
+ * Lives in shared so both the server-side Memory.store() merge and any
+ * client-side enrichment path (`MemoryClient.store(..., { enrichment })`,
+ * the MCP `store_memory` tool that goes through MCP sampling) can speak the
+ * exact same structural type without crossing the core→client circular
+ * dependency.
+ */
+interface EntityExtractionResult {
+    entities: Array<{
+        name: string;
+        type: string;
+    }>;
+    relations: Array<{
+        source: string;
+        target: string;
+        type: string;
+    }>;
+}
+/**
+ * Merge caller-provided entities/relationships with LLM-extracted ones.
+ *
+ * Caller-wins on case-insensitive name conflict — the caller's casing is
+ * preserved and extracted duplicates are skipped. Extracted relationships
+ * are appended only when both endpoints resolve (case-insensitively) to a
+ * final entity name; the endpoint strings on the appended relationship are
+ * rewritten to the canonical (final) casing.
+ *
+ * Pure function. Single canonical merge used by Memory.store(),
+ * MemoryClient.store() (HTTP client enrichment callback), and the MCP
+ * store_memory tool — three call sites cannot drift.
+ */
+declare function mergeExtractedEntities(callerEntities: IngestEntity[] | undefined, callerRelationships: IngestRelationship[] | undefined, extracted: EntityExtractionResult): {
+    entities: IngestEntity[];
+    relationships: IngestRelationship[];
+};
+
+interface ApiResponse<T> {
+    success: boolean;
+    data?: T;
+    error?: string;
+}
+/**
+ * Build variant of the running pyx-memory image. Detected from the actual
+ * availability of `@huggingface/transformers` at boot — `full` keeps the
+ * local-embedding stack bundled, `cloud` has it pruned (EMBEDDING_PROVIDER=http
+ * is mandatory). The detected value is authoritative; the optional
+ * `PYX_BUILD_VARIANT` env stamp is a sanity check that throws on drift.
+ */
+type TopologyServiceVariant = 'cloud' | 'full';
+/**
+ * Where embedding work happens. `inline` means the server computes vectors
+ * in-process (EMBEDDING_PROVIDER=local); `remote` means it delegates to an
+ * HTTP embedding service (EMBEDDING_PROVIDER=http). The endpoint URL itself
+ * is internal infrastructure and is intentionally NOT exposed here.
+ */
+type TopologyEmbeddingLocation = 'inline' | 'remote';
+/**
+ * Public topology snapshot returned by `GET /status`. Reflects actual runtime
+ * capability (variant detected from import probe, embedding location derived
+ * from configured provider) plus the active embedding profile. Never leaks
+ * embedding-service URLs or other infrastructure host fragments — those stay
+ * behind the admin surface.
+ */
+interface Topology {
+    service: {
+        variant: TopologyServiceVariant;
+        /**
+         * Operator-declared role label (`PYX_DEPLOYMENT_ROLE`). Free-form string.
+         * Structurally absent from the response when the env var is unset or empty.
+         */
+        declaredRole?: string;
+        version: string;
+    };
+    embedding: {
+        location: TopologyEmbeddingLocation;
+        modelKey: string;
+        modelId: string;
+        dimensions: number;
+    };
+}
+
 /** Metadata for a single image extracted from a PDF. */
 interface ExtractedImageMeta {
     imageId: string;
@@ -907,4 +1036,4 @@ interface PrincipalContext {
 /** Sentinel tenant ID used in single-tenant deployments. */
 declare const SINGLE_TENANT_ID = "_single";
 
-export { type AgentId, type ApiResponse, type ConsolidationRunResult, DEFAULTS, EmbeddingProviderName, type EnrichmentCallbacks, type ExtendedMemoryInterface, type GraphFailureMode, type GraphNode, type GraphRelationship, type GraphTraversalResult, type IngestEntity, type IngestErrorEvent, type IngestEvent, type IngestFileOptions, type IngestHeartbeatEvent, type IngestProgressEvent, type IngestRelationship, type IngestResultEvent, type IngestStage, type IngestionResult, MemoryClient, type MemoryClientOptions, type MemoryEntry, type MemoryIngestRequest, type MemoryInterface, type MemoryListParams, type MemoryListResult, type MemoryLogFilters, type MemorySearchParams, type MemorySearchResult, MemoryServerError, type MemoryStats, MemoryType, type MoveEntriesFilter, MoveFailureReason, type MoveResult, type MoveTarget, NamespaceIsolation, type PrincipalContext, RAGStrategy, SINGLE_TENANT_ID, SensitivityLevel, type StoreInput, StoreTarget, type TemporalQueryFilters, type TenantScopeOptions, type Timestamp, VectorProvider, type WikiLintReport };
+export { type AgentId, type ApiResponse, type ConsolidationRunResult, DEFAULTS, EmbeddingProviderName, type EnrichmentCallbacks, type EntityExtractionResult, type ExtendedMemoryInterface, type GraphFailureMode, type GraphNode, type GraphRelationship, type GraphTraversalResult, type IngestEntity, type IngestErrorEvent, type IngestEvent, type IngestFileOptions, type IngestHeartbeatEvent, type IngestProgressEvent, type IngestRelationship, type IngestResultEvent, type IngestStage, type IngestionResult, MemoryClient, type MemoryClientOptions, type MemoryEntry, type MemoryIngestRequest, type MemoryInterface, type MemoryListParams, type MemoryListResult, type MemoryLogFilters, type MemorySearchParams, type MemorySearchResult, MemoryServerError, type MemoryStats, MemoryType, type MoveEntriesFilter, MoveFailureReason, type MoveResult, type MoveTarget, NamespaceIsolation, type PrincipalContext, RAGStrategy, SINGLE_TENANT_ID, SensitivityLevel, type StoreInput, StoreTarget, type TemporalQueryFilters, type TenantScopeOptions, type Timestamp, type Topology, type TopologyServiceVariant, VectorProvider, type WikiLintReport, mergeExtractedEntities };

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import {
   MemoryClient,
   MemoryServerError
-} from "./chunk-D5PMQYZM.mjs";
+} from "./chunk-N6IRAUXH.mjs";
 import "./chunk-7P6ASYW6.mjs";
 
 // ../shared/src/constants/defaults.ts
@@ -11,6 +11,31 @@ var DEFAULTS = {
   MEMORY_SERVER_PORT: 7822
 };
 
+// ../shared/src/graph/extraction.ts
+function mergeExtractedEntities(callerEntities, callerRelationships, extracted) {
+  const entities = [...callerEntities ?? []];
+  const relationships = [...callerRelationships ?? []];
+  const nameByLowercase = /* @__PURE__ */ new Map();
+  for (const entity of entities) {
+    const key = entity.name.toLowerCase();
+    if (!nameByLowercase.has(key)) nameByLowercase.set(key, entity.name);
+  }
+  for (const entity of extracted.entities) {
+    const key = entity.name.toLowerCase();
+    if (nameByLowercase.has(key)) continue;
+    entities.push(entity);
+    nameByLowercase.set(key, entity.name);
+  }
+  for (const relationship of extracted.relations) {
+    const source = nameByLowercase.get(relationship.source.toLowerCase());
+    const target = nameByLowercase.get(relationship.target.toLowerCase());
+    if (source && target) {
+      relationships.push({ ...relationship, source, target });
+    }
+  }
+  return { entities, relationships };
+}
+
 // ../shared/src/types/isolation.ts
 var NamespaceIsolation = {
   SHARED: "shared",
@@ -88,5 +113,6 @@ export {
   SINGLE_TENANT_ID,
   SensitivityLevel,
   StoreTarget,
-  VectorProvider
+  VectorProvider,
+  mergeExtractedEntities
 };

package/dist/react.mjs

@@ -11,8 +11,8 @@ import {
   toGraphologyFormat,
   transformGraphData,
   unreachableHealth
-} from "./chunk-4DRKAXJE.mjs";
-import "./chunk-D5PMQYZM.mjs";
+} from "./chunk-47O2JYAP.mjs";
+import "./chunk-N6IRAUXH.mjs";
 import "./chunk-7P6ASYW6.mjs";
 
 // ../dashboard/src/hooks/use-consolidation-log.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyxmate/memory",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "type": "module",
   "description": "SDK for pyx-memory — Memory as a Service for AI agents",
   "license": "MIT",
@@ -57,7 +57,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@napi-rs/keyring": "^1.3.0"
+    "@napi-rs/keyring": "^1.3.0",
+    "@pyx-memory/shared": "workspace:*"
   },
   "devDependencies": {
     "tsup": "^8.4.0"