@pyxmate/memory 0.26.4 → 0.27.0

package/README.md

@@ -36,12 +36,12 @@ 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
+**That's the whole setup** — no extra server-side LLM API keys. Graph is a
+relational retrieval dimension, not a search-score boost. When content names
+people, organizations, tools, places, events, or key concepts, the caller LLM
+must pass both `entities` and `relationships`; edges matter as much as nodes because traversal
+needs them to connect related memories. The server does not auto-extract graph
+data and there is no regex fallback. 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.
 
@@ -68,7 +68,7 @@ await memory.store({
 const results = await memory.search({ query: 'deadline', limit: 5 });
 ```
 
-### Optional: client-side auto-extraction
+### Optional: caller-side extraction helper
 
 `MemoryClient.store(entry, options)` accepts an `enrichment.extractEntities`
 callback. The SDK invokes your callback (running against **your own** LLM
@@ -94,9 +94,11 @@ await memory.store(
 );
 ```
 
+Entity-free memories are valid. Store responses include `graphEntitiesWritten`
+and `graphRelationshipsWritten`, with zero making an omitted graph write visible.
 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.extractEntities: true` with no callback throws a loud error. The server
+never sees an LLM API key or runs regex extraction — it persists what you send.
 
 ## Entry Points
 

package/dist/cli/pyx-mem.mjs

@@ -516,7 +516,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 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.`;
+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. When content names people, organizations, tools, places, events, or key concepts, you (the caller) must extract and pass both entities and relationships \u2014 the server does not auto-extract them. Edges matter as much as nodes: without relationships the graph cannot connect related memories. Use file ingest for documents/images worth persisting; images require a description.`;
 
 // src/mcp/sampling.ts
 function createSamplingClient(server) {
@@ -15524,11 +15524,15 @@ var relationshipTypes = [
   "WORKS_AT",
   "LOCATED_IN"
 ];
+var storeTargets = ["sqlite", "vector", "graph"];
 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."),
   type: external_exports.enum(["short-term", "long-term", "working", "episodic", "summary"]).optional().describe("Memory type. Default long-term."),
+  targets: external_exports.array(external_exports.enum(storeTargets)).optional().describe(
+    "Storage targets. Include 'graph' when you provide entities/relationships or want zero graph write counts reported."
+  ),
   importance: external_exports.number().int().min(1).max(10).optional().describe("Importance 1\u201310."),
   eventTime: external_exports.string().optional().describe("ISO-8601 timestamp of when the event happened (bi-temporal)."),
   source: external_exports.string().optional().describe("Free-form origin (filename, URL, conversation id)."),
@@ -15541,7 +15545,7 @@ var inputShape7 = {
       type: external_exports.enum(entityTypes).describe("Entity type.")
     })
   ).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."
+    "Named entities mentioned by the content. The caller LLM must extract and pass these when the content names people, organizations, tools, places, events, or key concepts; the server does not auto-extract them."
   ),
   relationships: external_exports.array(
     external_exports.object({
@@ -15550,10 +15554,10 @@ var inputShape7 = {
       type: external_exports.enum(relationshipTypes).describe("Relationship type.")
     })
   ).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."
+    "Edges between entities; source and target must be entity names from this request. Relationships matter as much as entities because graph traversal needs edges to connect related memories."
   ),
   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)."
+    "Override extraction: false skips caller-side extraction; true requires caller entities or MCP sampling and errors loudly if neither is available."
   ),
   ...scopeShape
 };
@@ -15561,7 +15565,7 @@ 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 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.",
+    description: "Store one concise factual memory with required topic and project metadata. When content names people, organizations, tools, places, events, or key concepts, the caller LLM must extract and pass entities and relationships; the server does not auto-extract them. Relationships (edges) matter as much as entities because graph traversal needs edges to connect related memories. Entity-free memories are valid; omit graph data or set extractEntities:false when there are no graph facts.",
     inputSchema: inputShape7,
     annotations: { readOnlyHint: false, idempotentHint: false, openWorldHint: true }
   },
@@ -15575,12 +15579,14 @@ var storeMemoryTool = {
     const samplingAvailable = deps.samplingClient?.isAvailable() ?? false;
     const optedOut = args.extractEntities === false;
     const forced = args.extractEntities === true;
-    if (forced && !samplingAvailable) {
+    const graphTargeted = args.targets?.includes("graph") ?? true;
+    const hasCallerEntities = (entities?.length ?? 0) > 0;
+    if (forced && graphTargeted && !samplingAvailable && !hasCallerEntities) {
       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."
+        "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) {
+    if (graphTargeted && deps.samplingClient && samplingAvailable && !optedOut && !hasCallerEntities) {
       const prompt = buildExtractionPrompt(args.content);
       const completion = await deps.samplingClient.complete(
         prompt,
@@ -15594,6 +15600,7 @@ var storeMemoryTool = {
     const body = {
       content: args.content,
       type: args.type ?? "long-term",
+      targets: args.targets,
       metadata: {
         source: "agent",
         topic: args.topic,
@@ -15605,7 +15612,8 @@ var storeMemoryTool = {
       sessionId: args.sessionId,
       parentId: args.parentId,
       entities,
-      relationships
+      relationships,
+      ...args.extractEntities === false ? { extractEntities: false } : {}
     };
     const res = await http.requestJson({
       method: "POST",
@@ -15678,7 +15686,7 @@ 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.26.4" : "0.0.0-dev");
+  const version2 = opts.version ?? (true ? "0.27.0" : "0.0.0-dev");
   const server = new McpServer(
     { name: "pyx-memory", version: version2 },
     { instructions: PYX_MEMORY_INSTRUCTIONS, capabilities: { tools: {} } }
@@ -15865,7 +15873,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.
+To populate the knowledge graph, pass entities and relationships when you call store_memory \u2014 the server does not auto-extract them. Sampling-capable MCP clients can fill them from your own LLM; Claude Code does not advertise sampling, so extract and pass them yourself.
 `
   );
   return EXIT.OK;

package/dist/index.d.ts

@@ -482,6 +482,10 @@ interface MemoryEntry {
     sensitivity?: SensitivityLevel;
     /** Whether the content field is encrypted at rest. */
     encrypted?: boolean;
+    /** Number of graph entities written by this store call. Present on store responses. */
+    graphEntitiesWritten?: number;
+    /** Number of graph relationships written by this store call. Present on store responses. */
+    graphRelationshipsWritten?: number;
     /** Tenant ID for multi-tenant isolation. */
     tenantId?: string;
     /** User ID within the tenant. */
@@ -620,11 +624,11 @@ type StoreInput = Omit<MemoryEntry, 'id' | 'createdAt'> & {
     createdAt?: string;
     /** Storage targets. Default: ["sqlite", "vector"]. */
     targets?: StoreTarget[];
-    /** Agent-provided entities for graph storage. Required when targets includes "graph". */
+    /** Agent-provided entities for graph storage. */
     entities?: IngestEntity[];
     /** Agent-provided relationships for graph storage. */
     relationships?: IngestRelationship[];
-    /** Override server-side auto-extraction for this store call. */
+    /** Override graph entity extraction for this store call. */
     extractEntities?: boolean;
     /** Graph-failure handling. Default: "throw" (loud) — see GraphFailureMode. */
     graphFailureMode?: GraphFailureMode;
@@ -637,11 +641,11 @@ interface MemoryIngestRequest {
     sessionId?: string;
     /** Storage targets. Default: ["sqlite", "vector"]. */
     targets?: StoreTarget[];
-    /** Agent-provided entities for graph storage. Required when targets includes "graph". */
+    /** Agent-provided entities for graph storage. */
     entities?: IngestEntity[];
     /** Agent-provided relationships for graph storage. */
     relationships?: IngestRelationship[];
-    /** Override server-side auto-extraction for this ingest request. */
+    /** Override graph entity extraction for this ingest request. */
     extractEntities?: boolean;
     /** Graph-failure handling. Default: "throw" (loud) — see GraphFailureMode. */
     graphFailureMode?: GraphFailureMode;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyxmate/memory",
-  "version": "0.26.4",
+  "version": "0.27.0",
   "type": "module",
   "description": "SDK for pyx-memory — Memory as a Service for AI agents",
   "license": "MIT",