@pyxmate/memory 0.45.0 → 1.0.0

package/dist/cli/pyx-mem.mjs

@@ -1,8 +1,21 @@
 #!/usr/bin/env node
 import {
-  mergeExtractedEntities,
-  normalizeGraphLabel
-} from "../chunk-KSTI4M52.mjs";
+  PYX_MEMORY_INSTRUCTIONS,
+  SEARCH_ENUMERATION_CONCEPT_DESC,
+  SEARCH_LIMIT_DESC,
+  STORE_ENTITIES_DESC,
+  STORE_EVENT_TIME_DESC,
+  STORE_RELATIONSHIPS_DESC,
+  STORE_TOOL_DESC,
+  STORE_TRIPLES_DESC,
+  STRUCTURE_GRAPH_PROMPT_DESC,
+  buildDesignGuide,
+  buildGraphStructuringPrompt
+} from "../chunk-XHEVB23R.mjs";
+import {
+  normalizeGraphLabel,
+  normalizeNameKey
+} from "../chunk-X6AYWXW7.mjs";
 
 // src/cli/exit-codes.ts
 var EXIT = {
@@ -339,7 +352,7 @@ async function promptMasked(label) {
 `);
     return value;
   }
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve3, reject) => {
     const previousEncoding = stdin.readableEncoding;
     stdin.setEncoding("utf8");
     stdin.setRawMode(true);
@@ -357,7 +370,7 @@ async function promptMasked(label) {
         if (ch === "\n" || ch === "\r") {
           cleanup();
           stdout.write("\n");
-          resolve2(buf.trim());
+          resolve3(buf.trim());
           return;
         }
         if (ch === "") {
@@ -554,49 +567,33 @@ function createReadCredentials(providerFactory) {
 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. Pass eventTime (ISO-8601, when the fact happened or took effect) for any fact that can change or go stale \u2014 job/status changes, decisions that supersede earlier ones, dated events; recency ordering, dated ("as of") queries, and stale-vs-current conflict resolution all key off it. Search effort is retrieval depth: quick=strongest, deep=everything including archived/superseded. Use reinforce after memories were actually used, so they surface in quick/medium effort tiers. Use lineage for the history of how a fact changed; pass subject+relation for graph lineage or entryId for a superseded chain. Use record_correction when the user corrects a mistake you made (what was wrong, what to do instead, when it applies); call fetch_applicable_corrections before a task to retrieve the corrections that match it, then decide which to follow \u2014 pyx never auto-applies them. When a question names a time \u2014 explicit or relative ("last year", "\uB450 \uB2EC \uC804") \u2014 resolve it to an absolute ISO-8601 timestamp yourself and pass it as search anchorTime: results then rank by proximity to this time instead of now, without excluding anything. For count/list questions about a category, pass \`enumerationConcept\` = the language-agnostic/global category phrase (e.g. "fitness classes" / "\uC6B4\uB3D9 \uC218\uC5C5"); the caller-supplied hint is resolved by the embedding model, which covers a broad range of languages. pyx also auto-detects English/Korean count phrasing as a best-effort fallback when the hint is omitted. 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. For countable categories the user may later enumerate ("how many fitness classes / streaming services / pets do I have?"), add a canonical category CONCEPT node and an IS_A edge from each member to it. A language/synonym variant gives zero-cost exact-match resolution only when it is also a memberful CONCEPT node with member IS_A edges; there is no query-time alias\u2192canonical resolver. pyx resolves count/list category hints at query time via strict embedding over memberful CONCEPT nodes. 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;
-          }
+// src/mcp/prompts/index.ts
+import { z } from "zod";
+var structureGraphPrompt = {
+  name: "structure_graph",
+  description: STRUCTURE_GRAPH_PROMPT_DESC,
+  register(server) {
+    server.registerPrompt(
+      "structure_graph",
+      {
+        title: "Structure content into a knowledge graph",
+        description: STRUCTURE_GRAPH_PROMPT_DESC,
+        argsSchema: {
+          content: z.string().min(1).describe("The memory content to extract graph fields from.")
         }
-      }
-      throw new Error("MCP sampling returned no text content");
-    }
-  };
-}
+      },
+      ({ content }) => ({
+        messages: [
+          { role: "user", content: { type: "text", text: buildGraphStructuringPrompt(content) } }
+        ]
+      })
+    );
+  }
+};
+var ALL_PROMPTS = [structureGraphPrompt];
 
 // src/mcp/tools/corrections.ts
-import { z as z2 } from "zod";
+import { z as z3 } from "zod";
 
 // src/mcp/http-client.ts
 var DEFAULT_TIMEOUT_MS = 15e3;
@@ -703,22 +700,22 @@ function extractEnvelopeError(parsed) {
 }
 
 // src/mcp/tools/scopes.ts
-import { z } from "zod";
+import { z as z2 } from "zod";
 var scopeShape = {
-  tenantId: z.string().optional().describe("Sent as X-Tenant-Id for multi-tenant isolation."),
-  userId: z.string().optional().describe("Sent as X-User-Id."),
-  teamId: z.string().optional().describe("Sent as X-Team-Id."),
-  callerAccessLevel: z.enum(["public", "internal", "secret"]).optional().describe("Sent as X-Caller-Access-Level for sensitivity filtering.")
+  tenantId: z2.string().optional().describe("Sent as X-Tenant-Id for multi-tenant isolation."),
+  userId: z2.string().optional().describe("Sent as X-User-Id."),
+  teamId: z2.string().optional().describe("Sent as X-Team-Id."),
+  callerAccessLevel: z2.enum(["public", "internal", "secret"]).optional().describe("Sent as X-Caller-Access-Level for sensitivity filtering.")
 };
 
 // src/mcp/tools/corrections.ts
 var recordInputShape = {
-  namespaceId: z2.string().min(1).optional().describe("Namespace id to record into. Omit in single-tenant deployments (namespace-free)."),
-  whatWasWrong: z2.string().min(1).describe("What the agent did wrong."),
-  whatToDoInstead: z2.string().min(1).describe("The corrective instruction to follow instead."),
-  appliesWhen: z2.string().min(1).describe("When this correction applies \u2014 the task context future tasks are matched against."),
-  project: z2.string().optional().describe("Optional project scope; omit to apply to all projects."),
-  taskShape: z2.string().optional().describe("Optional task-shape hint stored for provenance."),
+  namespaceId: z3.string().min(1).optional().describe("Namespace id to record into. Omit in single-tenant deployments (namespace-free)."),
+  whatWasWrong: z3.string().min(1).describe("What the agent did wrong."),
+  whatToDoInstead: z3.string().min(1).describe("The corrective instruction to follow instead."),
+  appliesWhen: z3.string().min(1).describe("When this correction applies \u2014 the task context future tasks are matched against."),
+  project: z3.string().optional().describe("Optional project scope; omit to apply to all projects."),
+  taskShape: z3.string().optional().describe("Optional task-shape hint stored for provenance."),
   ...scopeShape
 };
 var recordCorrectionTool = {
@@ -751,10 +748,10 @@ var recordCorrectionTool = {
   }
 };
 var fetchInputShape = {
-  namespaceId: z2.string().min(1).optional().describe("Namespace id whose corrections to fetch. Omit in single-tenant deployments."),
-  taskShape: z2.string().min(1).describe("Shape of the task about to run \u2014 scored against each correction."),
-  project: z2.string().optional().describe("Optional project filter."),
-  limit: z2.number().int().positive().optional().describe("Max corrections to return (cap 5)."),
+  namespaceId: z3.string().min(1).optional().describe("Namespace id whose corrections to fetch. Omit in single-tenant deployments."),
+  taskShape: z3.string().min(1).describe("Shape of the task about to run \u2014 scored against each correction."),
+  project: z3.string().optional().describe("Optional project filter."),
+  limit: z3.number().int().positive().optional().describe("Max corrections to return (cap 5)."),
   ...scopeShape
 };
 var fetchApplicableCorrectionsTool = {
@@ -786,10 +783,10 @@ var fetchApplicableCorrectionsTool = {
 };
 
 // src/mcp/tools/delete.ts
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
 var inputShape = {
-  id: z3.string().min(1).describe("Required memory entry id to delete."),
-  reason: z3.string().min(1).describe("Required reason for deletion (audit)."),
+  id: z4.string().min(1).describe("Required memory entry id to delete."),
+  reason: z4.string().min(1).describe("Required reason for deletion (audit)."),
   ...scopeShape
 };
 var deleteMemoryTool = {
@@ -816,9 +813,9 @@ var deleteMemoryTool = {
 };
 
 // src/mcp/tools/get.ts
-import { z as z4 } from "zod";
+import { z as z5 } from "zod";
 var inputShape2 = {
-  id: z4.string().min(1).describe("Required memory entry id."),
+  id: z5.string().min(1).describe("Required memory entry id."),
   ...scopeShape
 };
 var getMemoryTool = {
@@ -846,17 +843,17 @@ var getMemoryTool = {
 // src/mcp/tools/ingest.ts
 import { readFile, stat } from "fs/promises";
 import { basename, extname, isAbsolute, resolve } from "path";
-import { z as z5 } from "zod";
+import { z as z6 } from "zod";
 var IMAGE_EXT = /* @__PURE__ */ new Set([".png", ".jpg", ".jpeg", ".webp", ".gif", ".bmp", ".tiff", ".svg"]);
 var MAX_BYTES = 50 * 1024 * 1024;
 var inputShape3 = {
-  path: z5.string().min(1).describe(
+  path: z6.string().min(1).describe(
     "Local file path readable by the pyx-mem process. Uploaded as multipart `file`. Images require `description`; documents auto-extract text."
   ),
-  description: z5.string().optional().describe(
+  description: z6.string().optional().describe(
     "REQUIRED for images so the entry is semantically searchable. Optional for documents with extractable text."
   ),
-  namespaceId: z5.string().optional().describe("Optional ReBAC namespace for entries created from this file."),
+  namespaceId: z6.string().optional().describe("Optional ReBAC namespace for entries created from this file."),
   ...scopeShape
 };
 var ingestMemoryFileTool = {
@@ -911,16 +908,16 @@ var ingestMemoryFileTool = {
 };
 
 // src/mcp/tools/lineage.ts
-import { z as z6 } from "zod";
+import { z as z7 } from "zod";
 var inputShape4 = {
-  subject: z6.string().optional().describe("Graph subject to trace, used with relation for graph lineage."),
-  relation: z6.string().optional().describe("Graph relation to trace for the subject."),
-  entryId: z6.string().optional().describe("Memory entry id to trace through its supersededBy chain."),
-  asOf: z6.string().optional().describe("Only include lineage versions ingested by this ISO-8601 time."),
-  eventTimeStart: z6.string().optional().describe("Inclusive event-time start (ISO-8601)."),
-  eventTimeEnd: z6.string().optional().describe("Inclusive event-time end (ISO-8601)."),
-  beforeValue: z6.string().optional().describe("Stop before the lineage version with this value."),
-  limit: z6.number().int().positive().optional().describe("Maximum lineage versions to return."),
+  subject: z7.string().optional().describe("Graph subject to trace, used with relation for graph lineage."),
+  relation: z7.string().optional().describe("Graph relation to trace for the subject."),
+  entryId: z7.string().optional().describe("Memory entry id to trace through its supersededBy chain."),
+  asOf: z7.string().optional().describe("Only include lineage versions ingested by this ISO-8601 time."),
+  eventTimeStart: z7.string().optional().describe("Inclusive event-time start (ISO-8601)."),
+  eventTimeEnd: z7.string().optional().describe("Inclusive event-time end (ISO-8601)."),
+  beforeValue: z7.string().optional().describe("Stop before the lineage version with this value."),
+  limit: z7.number().int().positive().optional().describe("Maximum lineage versions to return."),
   ...scopeShape
 };
 var lineageTool = {
@@ -956,16 +953,16 @@ var lineageTool = {
 };
 
 // src/mcp/tools/list.ts
-import { z as z7 } from "zod";
+import { z as z8 } from "zod";
 var inputShape5 = {
-  mode: z7.enum(["entries", "log"]).optional().describe(
+  mode: z8.enum(["entries", "log"]).optional().describe(
     "Listing mode. `entries` (default) returns paginated entries by filter; `log` returns the chronological memory log."
   ),
-  page: z7.number().int().min(1).optional().describe("1-based page index for entries mode."),
-  limit: z7.number().int().min(1).max(200).optional().describe("Page size; server clamps."),
-  type: z7.enum(["short-term", "long-term", "working", "episodic", "summary"]).optional().describe("Filter by memory type."),
-  agentId: z7.string().optional().describe("Filter to memories from this agentId."),
-  since: z7.string().optional().describe("ISO-8601 lower bound for log mode."),
+  page: z8.number().int().min(1).optional().describe("1-based page index for entries mode."),
+  limit: z8.number().int().min(1).max(200).optional().describe("Page size; server clamps."),
+  type: z8.enum(["short-term", "long-term", "working", "episodic", "summary"]).optional().describe("Filter by memory type."),
+  agentId: z8.string().optional().describe("Filter to memories from this agentId."),
+  since: z8.string().optional().describe("ISO-8601 lower bound for log mode."),
   ...scopeShape
 };
 var listMemoriesTool = {
@@ -1000,9 +997,9 @@ var listMemoriesTool = {
 };
 
 // src/mcp/tools/profile.ts
-import { z as z8 } from "zod";
+import { z as z9 } from "zod";
 var getInputShape = {
-  namespaceId: z8.string().min(1).describe("Namespace id whose user-profile to fetch."),
+  namespaceId: z9.string().min(1).describe("Namespace id whose user-profile to fetch."),
   ...scopeShape
 };
 var getUserProfileTool = {
@@ -1028,8 +1025,8 @@ var getUserProfileTool = {
   }
 };
 var upsertInputShape = {
-  namespaceId: z8.string().min(1).describe("Namespace id to upsert the user-profile into."),
-  content: z8.string().min(1).describe("Full freeform profile content (UTF-8, \u22648192 bytes; server enforces the cap)."),
+  namespaceId: z9.string().min(1).describe("Namespace id to upsert the user-profile into."),
+  content: z9.string().min(1).describe("Full freeform profile content (UTF-8, \u22648192 bytes; server enforces the cap)."),
   ...scopeShape
 };
 var upsertUserProfileTool = {
@@ -1056,11 +1053,11 @@ var upsertUserProfileTool = {
 };
 
 // src/mcp/tools/reinforce.ts
-import { z as z9 } from "zod";
+import { z as z10 } from "zod";
 var inputShape6 = {
-  entryIds: z9.array(z9.string().min(1)).min(1).describe("Memory entry ids that were actually used."),
-  signal: z9.enum(["context_included", "cited", "explicit_positive"]).describe("Reinforcement signal: context_included < cited < explicit_positive."),
-  at: z9.union([z9.string(), z9.number()]).optional().describe("Recall time as epoch-ms or full ISO-8601 timestamp with timezone."),
+  entryIds: z10.array(z10.string().min(1)).min(1).describe("Memory entry ids that were actually used."),
+  signal: z10.enum(["context_included", "cited", "explicit_positive"]).describe("Reinforcement signal: context_included < cited < explicit_positive."),
+  at: z10.union([z10.string(), z10.number()]).optional().describe("Recall time as epoch-ms or full ISO-8601 timestamp with timezone."),
   ...scopeShape
 };
 var reinforceTool = {
@@ -1087,31 +1084,27 @@ var reinforceTool = {
 };
 
 // src/mcp/tools/search.ts
-import { z as z10 } from "zod";
+import { z as z11 } from "zod";
 var inputShape7 = {
-  query: z10.string().min(1).describe("Required natural-language search text."),
-  limit: z10.number().int().min(1).max(100).optional().describe(
-    "Target result count; server clamps to 1\u2013100. Default 10. The hybrid strategy may widen count/list searches up to 30 for set-completeness recall when the caller passes `enumerationConcept`; English/Korean marker auto-detect is a best-effort fallback."
-  ),
-  strategy: z10.enum(["naive", "graph", "hybrid"]).optional().describe(
+  query: z11.string().min(1).describe("Required natural-language search text."),
+  limit: z11.number().int().min(1).max(100).optional().describe(SEARCH_LIMIT_DESC),
+  strategy: z11.enum(["naive", "graph", "hybrid"]).optional().describe(
     "RAG strategy. Defaults to `hybrid` (cross-encoder reranking, multi-entity decomposition, confidence scoring) and is sent explicitly when omitted; pass `naive` for a lighter vector-only search or `graph` for graph-augmented retrieval."
   ),
-  effort: z10.enum(["quick", "medium", "deep"]).optional().describe(
+  effort: z11.enum(["quick", "medium", "deep"]).optional().describe(
     "Retrieval depth: quick=strongest, medium=default-depth, deep=everything including archived/superseded."
   ),
-  type: z10.enum(["short-term", "long-term", "working", "episodic", "summary"]).optional().describe("Filter by memory type."),
-  agentId: z10.string().optional().describe("Filter to memories stored for this agentId."),
-  abstentionThreshold: z10.number().min(0).max(1).optional().describe("Enable confidence scoring; abstain when confidence falls below this value (0\u20131)."),
-  eventTimeStart: z10.string().optional().describe("Inclusive event-time start (ISO-8601); must be paired with eventTimeEnd."),
-  eventTimeEnd: z10.string().optional().describe("Inclusive event-time end (ISO-8601); must be paired with eventTimeStart."),
-  asOf: z10.string().optional().describe("Only include memories ingested before this ISO-8601 timestamp."),
-  anchorTime: z10.string().optional().describe(
+  type: z11.enum(["short-term", "long-term", "working", "episodic", "summary"]).optional().describe("Filter by memory type."),
+  agentId: z11.string().optional().describe("Filter to memories stored for this agentId."),
+  abstentionThreshold: z11.number().min(0).max(1).optional().describe("Enable confidence scoring; abstain when confidence falls below this value (0\u20131)."),
+  eventTimeStart: z11.string().optional().describe("Inclusive event-time start (ISO-8601); must be paired with eventTimeEnd."),
+  eventTimeEnd: z11.string().optional().describe("Inclusive event-time end (ISO-8601); must be paired with eventTimeStart."),
+  asOf: z11.string().optional().describe("Only include memories ingested before this ISO-8601 timestamp."),
+  anchorTime: z11.string().optional().describe(
     'Soft recency ANCHOR (ISO-8601) \u2014 ranks results by proximity to this time instead of now; never excludes anything. When the question names a relative time ("two months ago", "last year", "3\uB144 \uC804"), resolve it against the current date yourself and pass the absolute timestamp here; prefer this over eventTimeStart/End unless a strict window is required, because hard filters drop last-known-before facts.'
   ),
-  enumerationConcept: z10.string().trim().min(1).optional().describe(
-    'For count/list questions about a category, pass the language-agnostic/global category phrase here (for example, "fitness classes" or "\uC6B4\uB3D9 \uC218\uC5C5"). The embedding model resolves the caller-supplied hint across a broad range of languages.'
-  ),
-  enableRerank: z10.boolean().optional().describe(
+  enumerationConcept: z11.string().trim().min(1).optional().describe(SEARCH_ENUMERATION_CONCEPT_DESC),
+  enableRerank: z11.boolean().optional().describe(
     "Opt into multilingual cross-encoder reranking (hybrid strategy only). Sharply improves Korean/cross-lingual ordering at higher latency; leave off for the fast default path."
   ),
   ...scopeShape
@@ -1188,67 +1181,8 @@ var statusTool = {
 
 // src/mcp/tools/store.ts
 import { z as z12 } from "zod";
-
-// src/mcp/extraction-prompt.ts
-import { z as z11 } from "zod";
-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 = z11.object({
-  entities: z11.array(
-    z11.object({
-      name: z11.string().min(1),
-      type: z11.string().min(1).transform((value) => normalizeGraphLabel(value, "CONCEPT"))
-    })
-  ),
-  relations: z11.array(
-    z11.object({
-      source: z11.string().min(1),
-      target: z11.string().min(1),
-      type: z11.string().min(1).transform((value) => normalizeGraphLabel(value, "RELATED_TO"))
-    })
-  )
-});
-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}]}.`,
-    `Prefer EntityType values when applicable: ${ENTITY_TYPES.join(", ")}.`,
-    `Prefer RelationType values when applicable: ${RELATION_TYPES.join(", ")}.`,
-    "Emergent domain-specific labels are allowed; use uppercase words separated by underscores.",
-    "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 = [
+var preferredRelationshipTypes = [
   "USES",
   "OWNS",
   "DEPENDS_ON",
@@ -1259,7 +1193,12 @@ var relationshipTypes = [
   "WORKS_AT",
   "LOCATED_IN"
 ];
+var RELATIONSHIP_TYPE_DESC = `Relationship type \u2014 freeform label; preferred: ${preferredRelationshipTypes.join(", ")}.`;
 var storeTargets = ["sqlite", "vector", "graph"];
+var entityShape = z12.object({
+  name: z12.string().min(1).describe("Entity name as referenced in content."),
+  type: z12.enum(entityTypes).describe("Entity type.")
+});
 var inputShape9 = {
   content: z12.string().min(1).describe("Concise factual statement to persist; decision, not deliberation."),
   topic: z12.string().min(1).describe("Required metadata.topic for retrieval grouping."),
@@ -1269,71 +1208,81 @@ var inputShape9 = {
     "Storage targets. Include 'graph' when you provide entities/relationships or want zero graph write counts reported."
   ),
   importance: z12.number().int().min(1).max(10).optional().describe("Importance 1\u201310."),
-  eventTime: z12.string().optional().describe(
-    'ISO-8601 time the fact happened or took effect (bi-temporal). Pass for any fact that can change or go stale \u2014 recency ordering, dated ("as of") queries, and stale-vs-current conflict resolution key off it.'
-  ),
+  eventTime: z12.string().optional().describe(STORE_EVENT_TIME_DESC),
   source: z12.string().optional().describe("Free-form origin (filename, URL, conversation id)."),
   agentId: z12.string().optional().describe("Agent identifier stored alongside the entry."),
   sessionId: z12.string().optional().describe("Session identifier for grouping."),
   parentId: z12.string().optional().describe("Parent memory entry id (hierarchical)."),
-  entities: z12.array(
-    z12.object({
-      name: z12.string().min(1).describe("Entity name as referenced in content."),
-      type: z12.enum(entityTypes).describe("Entity type.")
-    })
-  ).optional().describe(
-    "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."
-  ),
+  entities: z12.array(entityShape).optional().describe(STORE_ENTITIES_DESC),
   relationships: z12.array(
     z12.object({
       source: z12.string().min(1).describe("Source entity name (must appear in entities array)."),
       target: z12.string().min(1).describe("Target entity name (must appear in entities array)."),
-      type: z12.enum(relationshipTypes).describe("Relationship type.")
+      type: z12.string().min(1).describe(RELATIONSHIP_TYPE_DESC)
     })
-  ).optional().describe(
-    '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. For countable categories the user may later enumerate ("how many fitness classes / streaming services / pets do I have?"), add a canonical category CONCEPT node and an IS_A edge from each member to it. A language/synonym variant gives zero-cost exact-match resolution only when it is also a memberful CONCEPT node with member IS_A edges; there is no query-time alias\u2192canonical resolver. pyx resolves un-enumerated count-noun variants at query time via strict embedding over memberful CONCEPT nodes.'
-  ),
+  ).optional().describe(STORE_RELATIONSHIPS_DESC),
+  triples: z12.array(
+    z12.object({
+      subject: entityShape.describe("Subject entity (source node)."),
+      relation: z12.string().min(1).describe(RELATIONSHIP_TYPE_DESC),
+      object: entityShape.describe("Object entity (target node).")
+    })
+  ).optional().describe(STORE_TRIPLES_DESC),
   extractEntities: z12.boolean().optional().describe(
-    "Override extraction: false skips caller-side extraction; true requires caller entities or MCP sampling and errors loudly if neither is available."
+    "Override extraction: false skips extraction; true asks the server-side extraction brain to run and errors loudly when none is configured."
+  ),
+  entitiesOnly: z12.boolean().optional().describe(
+    "Set true to deliberately store entities with no relationships (e.g. a single concept). Otherwise a graph store with 2+ entities and 0 relationships is refused so isolated nodes do not accumulate."
   ),
   ...scopeShape
 };
+function materializeGraphInput(args) {
+  const entities = /* @__PURE__ */ new Map();
+  const addEntity = (e) => {
+    const key = `${normalizeNameKey(e.name)}|${e.type}`;
+    if (!entities.has(key)) entities.set(key, e);
+  };
+  const relationships = /* @__PURE__ */ new Map();
+  const addRel = (rel) => {
+    const key = `${normalizeNameKey(rel.source)}|${normalizeNameKey(rel.target)}|${normalizeGraphLabel(rel.type, "RELATED_TO")}`;
+    if (!relationships.has(key)) relationships.set(key, rel);
+  };
+  for (const e of args.entities ?? []) addEntity(e);
+  for (const r of args.relationships ?? []) addRel(r);
+  for (const t of args.triples ?? []) {
+    addEntity(t.subject);
+    addEntity(t.object);
+    addRel({ source: t.subject.name, target: t.object.name, type: t.relation });
+  }
+  return { entities: [...entities.values()], relationships: [...relationships.values()] };
+}
 var storeMemoryTool = {
   name: "store_memory",
   config: {
     title: "Store pyx-memory entry",
-    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.",
+    description: STORE_TOOL_DESC,
     inputSchema: inputShape9,
     annotations: { readOnlyHint: false, idempotentHint: false, openWorldHint: true }
   },
-  handler: (deps) => async (raw, ctx) => {
+  handler: (deps) => async (raw) => {
     const args = raw;
+    const { entities, relationships } = materializeGraphInput(args);
+    const graphTargeted = !args.targets || args.targets.includes("graph");
+    const entityNameKeys = new Set(entities.map((e) => normalizeNameKey(e.name)));
+    const resolvableRelationships = relationships.filter((r) => {
+      const source = normalizeNameKey(r.source);
+      const target = normalizeNameKey(r.target);
+      return source !== target && entityNameKeys.has(source) && entityNameKeys.has(target);
+    }).length;
+    if (graphTargeted && entities.length >= 2 && resolvableRelationships === 0 && !args.entitiesOnly && args.extractEntities !== true) {
+      return mcpText(
+        `GRAPH_RELATIONSHIPS_REQUIRED: this store_memory call declares ${entities.length} entities but no relationship that connects them. Isolated nodes will not connect into the knowledge graph. Re-call store_memory with a \`relationships\` array (or \`triples\`) linking the entities (each { source, target, type }; source/target must be entity names from this call), OR set \`entitiesOnly: true\` if these entities are intentionally unconnected. Do not retry unchanged. If your MCP host exposes prompts, the \`structure_graph\` prompt produces the relationship/triple fields to add.`,
+        true
+      );
+    }
     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;
-    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."
-      );
-    }
-    if (graphTargeted && deps.samplingClient && samplingAvailable && !optedOut && !hasCallerEntities) {
-      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",
@@ -1348,9 +1297,9 @@ var storeMemoryTool = {
       agentId: args.agentId,
       sessionId: args.sessionId,
       parentId: args.parentId,
-      entities,
-      relationships,
-      ...args.extractEntities === false ? { extractEntities: false } : {}
+      entities: entities.length > 0 ? entities : void 0,
+      relationships: relationships.length > 0 ? relationships : void 0,
+      ...args.extractEntities !== void 0 ? { extractEntities: args.extractEntities } : {}
     };
     const res = await http.requestJson({
       method: "POST",
@@ -1391,7 +1340,7 @@ var summarizeMemoryEntityTool = {
       const res2 = await http.requestJson({
         method: "POST",
         path: "/api/memory/synthesis/entity",
-        body: { entityName: args.entityName, entityType: args.entityType },
+        body: { name: args.entityName, entityType: args.entityType },
         scope: args
       });
       return res2.ok ? mcpJson(res2.data) : res2.result;
@@ -1399,7 +1348,7 @@ var summarizeMemoryEntityTool = {
     const res = await http.requestJson({
       method: "GET",
       path: "/api/memory/synthesis/entity",
-      query: { entityName: args.entityName, entityType: args.entityType },
+      query: { name: args.entityName, entityType: args.entityType },
       scope: args
     });
     return res.ok ? mcpJson(res.data) : res.result;
@@ -1428,17 +1377,15 @@ var ALL_TOOL_NAMES = ALL_TOOLS.map((t) => t.name);
 // src/mcp/server.ts
 async function runMcpServer(opts) {
   const fetchImpl = opts.fetchImpl ?? fetch;
-  const version = opts.version ?? (true ? "0.45.0" : "0.0.0-dev");
+  const version = opts.version ?? (true ? "1.0.0" : "0.0.0-dev");
   const server = new McpServer(
     { name: "pyx-memory", version },
-    { instructions: PYX_MEMORY_INSTRUCTIONS, capabilities: { tools: {} } }
+    { instructions: PYX_MEMORY_INSTRUCTIONS, capabilities: { tools: {}, prompts: {} } }
   );
-  const samplingClient = createSamplingClient(server);
   for (const tool of ALL_TOOLS) {
     const handle = tool.handler({
       readCredentials: opts.readCredentials,
-      fetchImpl,
-      samplingClient
+      fetchImpl
     });
     server.registerTool(
       tool.name,
@@ -1446,9 +1393,12 @@ async function runMcpServer(opts) {
       async (args, extra) => handle(args, { signal: extra?.signal })
     );
   }
+  for (const prompt of ALL_PROMPTS) {
+    prompt.register(server);
+  }
   const transport = new StdioServerTransport();
-  const closed = new Promise((resolve2) => {
-    transport.onclose = () => resolve2();
+  const closed = new Promise((resolve3) => {
+    transport.onclose = () => resolve3();
   });
   await server.connect(transport);
   await closed;
@@ -1457,9 +1407,9 @@ async function runMcpServer(opts) {
 // src/cli/commands/mcp.ts
 async function mcpCommand() {
   const readCredentials = createReadCredentials(() => getDefaultKeychain());
-  const onStdinEnd = new Promise((resolve2) => {
-    process.stdin.once("end", resolve2);
-    process.stdin.once("close", resolve2);
+  const onStdinEnd = new Promise((resolve3) => {
+    process.stdin.once("end", resolve3);
+    process.stdin.once("close", resolve3);
   });
   try {
     await Promise.race([runMcpServer({ readCredentials }), onStdinEnd]);
@@ -1615,7 +1565,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.
-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.
+To populate the knowledge graph, YOU pass entities and relationships (or triples) \u2014 a multi-entity store needs at least one connecting edge or it is refused. The server does not extract for you unless a self-host operator configured a BYO extraction endpoint (then store_memory can forward extractEntities:true). Images require caller-provided descriptions/hooks.
 `
   );
   return EXIT.OK;
@@ -1919,6 +1869,183 @@ function writeJsonAndReport(filePath, agentLabel, opts = {}) {
   return result.exitCode;
 }
 
+// src/cli/commands/scaffold.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, statSync, writeFileSync as writeFileSync2 } from "fs";
+import { basename as basename2, join as join2, resolve as resolve2 } from "path";
+var SERVER_IMAGE = "ghcr.io/pyx-corp/pyx-memory-v1:latest";
+var DOCKER_COMPOSE = `services:
+  pyx-memory:
+    image: ${SERVER_IMAGE}
+    ports:
+      - "7822:7822"
+    volumes:
+      - pyx-memory-data:/data
+    environment:
+      DATA_DIR: "\${DATA_DIR:-/data}"
+      API_KEY: "\${API_KEY:-}"
+      ADMIN_API_KEY: "\${ADMIN_API_KEY:-}"
+      TENANT_MODE: "\${TENANT_MODE:-single}"
+      NEO4J_URL: "\${NEO4J_URL:-bolt://neo4j:7687}"
+      NEO4J_USERNAME: "\${NEO4J_USERNAME:-neo4j}"
+      NEO4J_PASSWORD: "\${NEO4J_PASSWORD:?Set NEO4J_PASSWORD in .env or the shell.}"
+      EMBEDDING_PROVIDER: "\${EMBEDDING_PROVIDER:-local}"
+      EMBEDDING_ENDPOINT: "\${EMBEDDING_ENDPOINT:-}"
+      EMBEDDING_DIMENSIONS: "\${EMBEDDING_DIMENSIONS:-}"
+      # Graph is built by the CALLING AGENT by default (it passes entities +
+      # relationships / triples) \u2014 the server runs no LLM. To opt into
+      # server-side BYO extraction, set EXTRACTION_PROVIDER=http and supply
+      # EXTRACTION_ENDPOINT in .env.
+      EXTRACTION_PROVIDER: "\${EXTRACTION_PROVIDER:-none}"
+      EXTRACTION_ENDPOINT: "\${EXTRACTION_ENDPOINT:-}"
+      EXTRACTION_API_KEY: "\${EXTRACTION_API_KEY:-}"
+      EXTRACTION_MODEL: "\${EXTRACTION_MODEL:-}"
+      ENCRYPTION_KEY: "\${ENCRYPTION_KEY:-}"
+    depends_on:
+      neo4j:
+        condition: service_healthy
+
+  neo4j:
+    image: neo4j:5-community
+    ports:
+      - "7474:7474"
+      - "7687:7687"
+    volumes:
+      - pyx-memory-neo4j-data:/data
+      - pyx-memory-neo4j-logs:/logs
+    environment:
+      NEO4J_AUTH: "neo4j/\${NEO4J_PASSWORD:?Set NEO4J_PASSWORD in .env or the shell.}"
+      NEO4J_PLUGINS: '["apoc"]'
+    healthcheck:
+      test: ["CMD", "neo4j", "status"]
+      interval: 10s
+      timeout: 10s
+      retries: 10
+
+volumes:
+  pyx-memory-data:
+  pyx-memory-neo4j-data:
+  pyx-memory-neo4j-logs:
+`;
+var ENV_EXAMPLE = `# pyx-memory operator config
+# Copy this file to .env, then fill the required values before running Docker Compose.
+
+# OPTIONAL. Graph is built by the calling agent by default (the server runs no LLM).
+# Set to http ONLY to opt into server-side BYO entity/relationship extraction.
+EXTRACTION_PROVIDER=none
+
+# REQUIRED only when EXTRACTION_PROVIDER=http. HTTP chat/completions-compatible base URL.
+# Leave empty for the default agent-owns-the-graph setup.
+EXTRACTION_ENDPOINT=
+
+# OPTIONAL. Bearer token sent to EXTRACTION_ENDPOINT when your extraction service requires auth.
+EXTRACTION_API_KEY=
+
+# OPTIONAL. Model identifier sent to the extraction service.
+EXTRACTION_MODEL=
+
+# OPTIONAL for local embeddings. Set to http only when using a remote embedding service.
+EMBEDDING_PROVIDER=local
+
+# REQUIRED only when EMBEDDING_PROVIDER=http. Base URL for the HTTP embedding service.
+EMBEDDING_ENDPOINT=
+
+# REQUIRED only when EMBEDDING_PROVIDER=http. Must match the remote embedding vector width.
+# Example for embeddinggemma: 768.
+EMBEDDING_DIMENSIONS=
+
+# RECOMMENDED for any protected or production deployment. Empty means unauthenticated local access.
+API_KEY=
+
+# OPTIONAL. Destructive/admin operations use this; when empty, the server falls back to API_KEY.
+ADMIN_API_KEY=
+
+# REQUIRED only when SENSITIVITY_POLICY=encrypt is configured on the server.
+# 32 bytes as 64 hex chars or 44 base64 chars.
+ENCRYPTION_KEY=
+
+# REQUIRED by the scaffolded container.
+DATA_DIR=/data
+
+# REQUIRED. Use single for one app/tenant; use multi only behind authenticated tenant routing.
+TENANT_MODE=single
+
+# REQUIRED for graph storage in this compose stack.
+NEO4J_URL=bolt://neo4j:7687
+
+# OPTIONAL. Defaults to neo4j when unset.
+NEO4J_USERNAME=neo4j
+
+# REQUIRED by docker-compose.yml for the Neo4j service and pyx-memory graph connection.
+NEO4J_PASSWORD=
+`;
+var MEMORY_TS = `import { createPyxMemory } from '@pyxmate/memory';
+
+// Reads PYX_MEMORY_URL and PYX_MEMORY_API_KEY by default.
+export const memory = createPyxMemory();
+`;
+function resolveTarget(args) {
+  const cwd = args.cwd ?? process.cwd();
+  if (args.name === true) {
+    process.stderr.write("Error: --name requires a directory name.\n");
+    return null;
+  }
+  const trimmedName = typeof args.name === "string" ? args.name.trim() : "";
+  if (typeof args.name === "string" && trimmedName.length === 0) {
+    process.stderr.write("Error: --name requires a non-empty directory name.\n");
+    return null;
+  }
+  const targetDir = trimmedName ? resolve2(cwd, trimmedName) : cwd;
+  const appName = trimmedName || basename2(resolve2(cwd));
+  return { targetDir, appName };
+}
+function buildFiles(targetDir, appName) {
+  return [
+    { path: join2(targetDir, "docker-compose.yml"), contents: DOCKER_COMPOSE },
+    { path: join2(targetDir, ".env.example"), contents: ENV_EXAMPLE },
+    { path: join2(targetDir, "memory.ts"), contents: MEMORY_TS },
+    {
+      path: join2(targetDir, "PYX_MEMORY_DESIGN_GUIDE.md"),
+      contents: buildDesignGuide({ appName })
+    }
+  ];
+}
+function scaffoldCommand(args = {}) {
+  const target = resolveTarget(args);
+  if (target === null) return EXIT.USAGE;
+  if (existsSync2(target.targetDir) && !statSync(target.targetDir).isDirectory()) {
+    process.stderr.write(`Error: target exists and is not a directory: ${target.targetDir}
+`);
+    return EXIT.USAGE;
+  }
+  mkdirSync2(target.targetDir, { recursive: true });
+  const created = [];
+  const skipped = [];
+  for (const file of buildFiles(target.targetDir, target.appName)) {
+    const relativePath = basename2(file.path);
+    if (existsSync2(file.path)) {
+      skipped.push(relativePath);
+      continue;
+    }
+    writeFileSync2(file.path, file.contents, "utf8");
+    created.push(relativePath);
+  }
+  process.stdout.write(
+    [
+      `pyx-memory scaffold: ${target.targetDir}`,
+      `created: ${created.length > 0 ? created.join(", ") : "(none)"}`,
+      `skipped: ${skipped.length > 0 ? skipped.join(", ") : "(none)"}`,
+      "",
+      "Next steps:",
+      "1. Copy .env.example to .env and set NEO4J_PASSWORD (graph is built by the calling agent by default \u2014 set EXTRACTION_* only to opt into server-side BYO extraction).",
+      "2. Set API_KEY before using this beyond local development.",
+      "3. Run: docker compose up -d",
+      "4. Set PYX_MEMORY_URL=http://localhost:7822 and PYX_MEMORY_API_KEY to match API_KEY.",
+      ""
+    ].join("\n")
+  );
+  return EXIT.OK;
+}
+
 // src/cli/commands/status.ts
 async function statusCommand(opts = {}) {
   const provider = opts.keychain ?? getDefaultKeychain();
@@ -1973,6 +2100,7 @@ Commands:
   status [--json]                              Show endpoint, key presence, MCP config status.
   logout                                       Delete stored pyx-memory credentials.
   doctor [--json]                              Diagnose keychain, credentials, backend, MCP startup.
+  scaffold [--name <dir>]                      Generate Docker, env, SDK, and memory design-guide starter files.
   mcp                                          Start stdio MCP server.
   mcp install <target> [--scope user|local|project]
                                                Install pyx-memory MCP config for your AI agent.
@@ -2089,6 +2217,8 @@ async function main() {
       return logoutCommand();
     case "doctor":
       return doctorCommand({ json: parsed.flags.json === true });
+    case "scaffold":
+      return scaffoldCommand({ name: parsed.flags.name });
     case "mcp":
       return runMcpCommand(parsed);
     default: