@pyxmate/memory 0.45.1 → 1.0.0

package/README.md

@@ -38,14 +38,13 @@ Restart Claude Code. The MCP tools are auto-discovered via MCP Tool Search:
 `get_user_profile`, `upsert_user_profile`, `record_correction`, and
 `fetch_applicable_corrections`.
 
-**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.
+**That's the whole setup.** Graph is a relational retrieval dimension, not a
+search-score boost. When content names people, organizations, tools, places,
+events, or key concepts, pass both `entities` and `relationships` when you can
+(caller-wins); edges matter as much as nodes because traversal needs them to
+connect related memories. Server-side text/entity extraction runs only when an
+extraction brain is configured; otherwise callers must pass graph data or use
+caller-side hooks. Images always require caller-provided descriptions/hooks.
 
 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
@@ -99,8 +98,8 @@ 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. The server
-never sees an LLM API key or runs regex extraction — it persists what you send.
+`entry.extractEntities: true` with no callback forwards the hint to the server
+brain, which loud-fails if it is not configured.
 
 ## Entry Points
 

package/dist/agent-contract.d.ts

@@ -0,0 +1,40 @@
+declare const 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. Isolation: userId/teamId are attribution and legacy filters, not authorization or read gates. Use agentId only for trusted per-agent pool isolation (hard filter when set; omit to share a pool); on hosted MaaS/remote MCP it is a within-tenant filter, not a cross-identity security boundary. For per-user/team privacy inside a shared tenant, use namespaces + ReBAC grants via /api/admin/* + ADMIN_API_KEY + TENANT_MODE=multi. callerAccessLevel is sensitivity redaction, not isolation. Trusted stdio/self-host/companion callers may pass scope per call; hosted MaaS/remote MCP derive identity from project/token and strip caller-supplied identity until verified-JWT multi-tenant remote MCP exists. 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, pass entities and relationships when you can (caller-wins). You build the graph \u2014 the server does not extract it for you unless a self-host operator has configured a BYO extraction endpoint (then caller-passed graph still wins). On a multi-entity store, include at least one relationship connecting the entities, or the store is refused so isolated nodes never accumulate (set entitiesOnly for a deliberate lone entity); triples make edges impossible to omit. 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.";
+declare const PERSISTENT_MEMORY_SECTION: string;
+declare function buildDesignGuide({ appName }: {
+    appName: string;
+}): string;
+declare const AGENT_TARGETS: readonly [{
+    readonly tool: "Claude Code";
+    readonly instructionsFile: "~/.claude/CLAUDE.md";
+}, {
+    readonly tool: "Codex CLI";
+    readonly instructionsFile: "~/.codex/AGENTS.md";
+}, {
+    readonly tool: "oh-my-pi (omp)";
+    readonly instructionsFile: "~/.omp/agent/RULES.md";
+}, {
+    readonly tool: "Gemini CLI";
+    readonly instructionsFile: "~/.gemini/GEMINI.md";
+}, {
+    readonly tool: "Any other tool";
+    readonly instructionsFile: "that tool's user-scope (global) instructions/rules file";
+}];
+declare const STORE_ENTITIES_DESC = "Named entities mentioned by the content. Pass entities and relationships when you can (caller-wins). You build the graph \u2014 the server does not extract it for you unless a self-host operator has configured a BYO extraction endpoint (then caller-passed graph still wins). On a multi-entity store, include at least one relationship connecting the entities, or the store is refused so isolated nodes never accumulate (set entitiesOnly for a deliberate lone entity); triples make edges impossible to omit.";
+declare const STORE_RELATIONSHIPS_DESC = "Edges between entities; source and target must be entity names from this request. Pass entities and relationships when you can (caller-wins). You build the graph \u2014 the server does not extract it for you unless a self-host operator has configured a BYO extraction endpoint (then caller-passed graph still wins). On a multi-entity store, include at least one relationship connecting the entities, or the store is refused so isolated nodes never accumulate (set entitiesOnly for a deliberate lone entity); triples make edges impossible to omit. 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.";
+declare const STORE_TRIPLES_DESC = "Graph facts as subject\u2013relation\u2013object triples; each is materialized into the two entity nodes plus the edge that connects them, so a node cannot be added without its relationship. Use this (or entities + relationships) to populate the knowledge graph \u2014 for weak hosts triples make edges unavoidable. subject/object each have a name and a type (from the entity-type set); relation is a freeform label. Merged with any entities/relationships you also pass (caller-wins); duplicates within one call are collapsed.";
+declare const STORE_EVENT_TIME_DESC = "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.";
+declare const STORE_TOOL_DESC = "Store one concise factual memory with required topic and project metadata. When content names people, organizations, tools, places, events, or key concepts, pass entities and relationships when you can (caller-wins). You build the graph \u2014 the server does not extract it for you unless a self-host operator has configured a BYO extraction endpoint (then caller-passed graph still wins). On a multi-entity store, include at least one relationship connecting the entities, or the store is refused so isolated nodes never accumulate (set entitiesOnly for a deliberate lone entity); triples make edges impossible to omit. 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.";
+declare const SEARCH_LIMIT_DESC = "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.";
+declare const SEARCH_ENUMERATION_CONCEPT_DESC = "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.";
+declare const STRUCTURE_GRAPH_PROMPT_DESC = "Returns a prompt that extracts the graph fields (triples, or entities + relationships) to include in a store_memory call \u2014 run it with your own LLM, then add the JSON it returns to your store_memory arguments (you still supply content/topic/project). Useful when store_memory returns GRAPH_RELATIONSHIPS_REQUIRED, or for any content with graph-worthy facts. This prompt is executed by your agent, not the server.";
+/**
+ * Server-owned template the agent runs with its OWN LLM to extract the GRAPH
+ * FIELDS (not the whole store_memory call — the agent supplies content/topic/
+ * project) from `content`, with entities linked by edges. Deterministic string
+ * (no server LLM); the single source for the `structure_graph` MCP prompt.
+ * Triples-first so edges are unavoidable.
+ */
+declare function buildGraphStructuringPrompt(content: string): string;
+declare function buildAgentSnippet(): string;
+
+export { AGENT_TARGETS, PERSISTENT_MEMORY_SECTION, 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, buildAgentSnippet, buildDesignGuide, buildGraphStructuringPrompt };

package/dist/agent-contract.mjs

@@ -0,0 +1,32 @@
+import {
+  AGENT_TARGETS,
+  PERSISTENT_MEMORY_SECTION,
+  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,
+  buildAgentSnippet,
+  buildDesignGuide,
+  buildGraphStructuringPrompt
+} from "./chunk-XHEVB23R.mjs";
+export {
+  AGENT_TARGETS,
+  PERSISTENT_MEMORY_SECTION,
+  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,
+  buildAgentSnippet,
+  buildDesignGuide,
+  buildGraphStructuringPrompt
+};

package/dist/{chunk-UV2DFSKR.mjs → chunk-PXQLVQAA.mjs}

@@ -1,6 +1,6 @@
 import {
   mergeExtractedEntities
-} from "./chunk-KSTI4M52.mjs";
+} from "./chunk-X6AYWXW7.mjs";
 
 // ../client/src/memory-client.ts
 var MemoryServerError = class extends Error {
@@ -57,12 +57,6 @@ var MemoryClient = class {
   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({

package/dist/{chunk-KSTI4M52.mjs → chunk-X6AYWXW7.mjs}

@@ -10,6 +10,16 @@ function normalizeGraphLabel(value, fallback) {
   const normalized = value.trim().toUpperCase().replace(/[^A-Z0-9]+/g, "_").replace(/^_+|_+$/g, "");
   return normalized.length > 0 ? normalized : fallback;
 }
+function normalizeNameKey(name) {
+  return name.trim().toLowerCase().replace(/\s+/g, " ");
+}
+function relationshipKey(relationship) {
+  return [
+    relationship.source.trim().toLowerCase(),
+    relationship.target.trim().toLowerCase(),
+    normalizeGraphLabel(relationship.type, "RELATED_TO")
+  ].join("\0");
+}
 function mergeExtractedEntities(callerEntities, callerRelationships, extracted) {
   const entities = [...callerEntities ?? []];
   const relationships = [...callerRelationships ?? []];
@@ -36,7 +46,15 @@ function mergeExtractedEntities(callerEntities, callerRelationships, extracted)
       });
     }
   }
-  return { entities, relationships };
+  const seenRelationships = /* @__PURE__ */ new Set();
+  const dedupedRelationships = [];
+  for (const relationship of relationships) {
+    const key = relationshipKey(relationship);
+    if (seenRelationships.has(key)) continue;
+    seenRelationships.add(key);
+    dedupedRelationships.push(relationship);
+  }
+  return { entities, relationships: dedupedRelationships };
 }
 
 // ../shared/src/types/isolation.ts
@@ -110,6 +128,7 @@ var SINGLE_TENANT_ID = "_single";
 export {
   DEFAULTS,
   normalizeGraphLabel,
+  normalizeNameKey,
   mergeExtractedEntities,
   NamespaceIsolation,
   MemoryType,

package/dist/chunk-XHEVB23R.mjs

@@ -0,0 +1,169 @@
+// src/contract/index.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. Isolation: userId/teamId are attribution and legacy filters, not authorization or read gates. Use agentId only for trusted per-agent pool isolation (hard filter when set; omit to share a pool); on hosted MaaS/remote MCP it is a within-tenant filter, not a cross-identity security boundary. For per-user/team privacy inside a shared tenant, use namespaces + ReBAC grants via /api/admin/* + ADMIN_API_KEY + TENANT_MODE=multi. callerAccessLevel is sensitivity redaction, not isolation. Trusted stdio/self-host/companion callers may pass scope per call; hosted MaaS/remote MCP derive identity from project/token and strip caller-supplied identity until verified-JWT multi-tenant remote MCP exists. 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, pass entities and relationships when you can (caller-wins). You build the graph \u2014 the server does not extract it for you unless a self-host operator has configured a BYO extraction endpoint (then caller-passed graph still wins). On a multi-entity store, include at least one relationship connecting the entities, or the store is refused so isolated nodes never accumulate (set entitiesOnly for a deliberate lone entity); triples make edges impossible to omit. 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.`;
+var PERSISTENT_MEMORY_SECTION = [
+  "## Persistent Memory",
+  "",
+  "Use the configured `pyx-memory` MCP tools for durable memory across conversations.",
+  "",
+  "Search before assuming:",
+  "",
+  "- At the start of a new conversation or task, search for the project name and task topic.",
+  "- Before suggesting an approach, check whether prior decisions contradict it.",
+  "- When the user references prior work, search for it.",
+  "- When investigating a bug, search for prior occurrences.",
+  '- When a question names a time \u2014 explicit or relative ("last year", "\uB450 \uB2EC \uC804") \u2014 resolve it to an absolute ISO-8601 timestamp and pass it as search `anchorTime`: results rank by proximity to that time instead of now, without excluding anything.',
+  "- Match search `effort` to the task: `quick` (default \u2014 the strongest, most-used memories) for routine recall; `deep` (everything, including archived and superseded) when `quick` returns nothing or you need full history.",
+  '- To trace how a fact changed over time ("what did X use before Y", how it evolved), call `lineage` \u2014 pass `subject` + `relation` for graph lineage, or an `entryId` for a superseded chain \u2014 instead of stitching together multiple searches.',
+  "",
+  "Reinforce what you use:",
+  "",
+  "- After a retrieved memory actually informs your work (you cited it or acted on it), call `reinforce` on that memory. Recall is what keeps a memory strong: without it, memories fade out of the `quick`/`medium` tiers over time (idle never revives them \u2014 only reinforcement does).",
+  "",
+  "Apply corrections instead of repeating mistakes:",
+  "",
+  "- When the user corrects a mistake you made, call `record_correction` (what was wrong, what to do instead, and when it applies). Before starting a task, call `fetch_applicable_corrections` with the task shape to retrieve the corrections that match it, then decide which to follow \u2014 pyx never auto-applies them. Isolation: `userId`/`teamId` are attribution and legacy filters, not authorization or read gates. Use `agentId` only for trusted per-agent pool isolation (hard filter when set; omit to share a pool); on hosted MaaS/remote MCP it is a within-tenant filter, not a cross-identity security boundary. For per-user/team privacy inside a shared tenant, use namespaces + ReBAC grants via `/api/admin/*` + `ADMIN_API_KEY` + `TENANT_MODE=multi` (private namespace per identity; grant everyone for shared). `callerAccessLevel` is sensitivity redaction, not isolation. Trust boundary: stdio/self-host/companion callers may pass scope per call; hosted MaaS/remote MCP derive identity from the project/token and strip or ignore caller-supplied identity until verified-JWT multi-tenant remote MCP exists.",
+  "",
+  "Store immediately after:",
+  "",
+  "- User corrections or workflow/tool preferences.",
+  "- Bug fixes, with root cause and solution.",
+  "- Architecture or design decisions, with reasoning.",
+  "- Integration details such as API format, auth flow, endpoint behavior, or tool behavior.",
+  "- Gotchas or pitfalls, with what went wrong and the fix.",
+  '- Explicit "remember this" requests.',
+  "",
+  "Memory rules:",
+  "",
+  "- Always include `topic` and `project`.",
+  "- Store concise facts and decisions, not deliberation.",
+  "- Keep one memory per concept \u2014 do not bundle unrelated facts.",
+  "- Do not store ephemeral file contents, current state, or in-progress work.",
+  '- 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; facts without `eventTime` cannot be ordered in time.',
+  '- Graph is a relational retrieval dimension, not a boost. When content names people, organizations, tools, places, events, or key concepts, pass `entities` and `relationships` when you can (caller-wins). You build the graph \u2014 the server does not extract it for you unless a self-host operator has configured a BYO extraction endpoint (then caller-passed graph still wins). On a multi-entity store, include at least one relationship connecting the entities, or the store is refused so isolated nodes never accumulate (set entitiesOnly for a deliberate lone entity); triples make edges impossible to omit. Relationships (edges) matter as much as entities because traversal needs edges to connect related memories. Entity-free memories are valid; zero graph writes are reported as counts. 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 (`"yoga"` IS_A `"fitness classes"`). 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. On count/list searches, pass `enumerationConcept` as the language-agnostic/global category phrase; the embedding model resolves the caller-supplied hint across a broad range of languages, and English/Korean marker auto-detect is only a fallback.',
+  "- Ingest documents/images only when they are worth persisting; images require a",
+  "  short description so they are searchable."
+].join("\n");
+function buildDesignGuide({ appName }) {
+  const name = appName.trim() || "your app";
+  return [
+    `# ${name} pyx-memory Design Guide`,
+    "",
+    "This guide is generated from the canonical pyx-memory agent contract. Keep the global rules intact, then fill in the app-specific policy sections below.",
+    "",
+    PERSISTENT_MEMORY_SECTION,
+    "",
+    `## ${name} Fill-In Scaffold`,
+    "",
+    "### What IS Worth Remembering In This App",
+    "",
+    "- [ ] Durable user preferences, decisions, facts, corrections, workflows, and integration details that should survive across sessions.",
+    "- [ ] Bug fixes or operational gotchas only after the root cause and fix are known.",
+    "",
+    "### What NOT To Store",
+    "",
+    "- [ ] Ephemeral UI state, transient progress, raw logs, draft deliberation, duplicate facts, or data that belongs in the product database instead of the memory layer.",
+    "- [ ] Secrets, credentials, payment data, private keys, or sensitive payloads unless your app has an explicit policy and encryption posture for them.",
+    "",
+    "### eventTime Rules",
+    "",
+    "- [ ] Pass `eventTime` as an ISO-8601 timestamp for any fact whose ordering can change the answer later.",
+    "- [ ] Use the time the fact happened or took effect, not the time the agent noticed it.",
+    "",
+    "### Entity And Relationship Expectations",
+    "",
+    "- [ ] When content names people, organizations, tools, places, events, or key concepts, pass both `entities` and `relationships` when the caller already knows them.",
+    "- [ ] Treat graph edges as retrieval structure, not decoration; add `IS_A` category edges for count/list questions users may ask later.",
+    "- [ ] The calling agent builds the graph: pass `entities` + `relationships` (or `triples`), and connect multi-entity stores with at least one relationship. Server-side extraction is OFF by default \u2014 opt in only by configuring a self-host BYO extraction endpoint.",
+    "",
+    "### Privacy And Sensitivity",
+    "",
+    "- [ ] Define which memory topics are public, internal, or secret for this app.",
+    "- [ ] Decide what must be blocked, redacted, encrypted, or never sent to an external extraction endpoint.",
+    "",
+    "### Image Description Policy",
+    "",
+    "- [ ] Images require caller-provided descriptions from your app or agent vision hook before they become semantically searchable.",
+    "- [ ] The thin SDK preset does not understand images; it only creates an HTTP `MemoryClient`.",
+    "",
+    "### Parity Scope",
+    "",
+    "- [ ] pyx-memory parity is the memory layer: the enrichment/file-memory glue collapses into this generated contract and the HTTP client. Product-specific orchestration still belongs to the app."
+  ].join("\n");
+}
+var AGENT_TARGETS = [
+  { tool: "Claude Code", instructionsFile: "~/.claude/CLAUDE.md" },
+  { tool: "Codex CLI", instructionsFile: "~/.codex/AGENTS.md" },
+  { tool: "oh-my-pi (omp)", instructionsFile: "~/.omp/agent/RULES.md" },
+  { tool: "Gemini CLI", instructionsFile: "~/.gemini/GEMINI.md" },
+  {
+    tool: "Any other tool",
+    instructionsFile: "that tool's user-scope (global) instructions/rules file"
+  }
+];
+var STORE_ENTITIES_DESC = "Named entities mentioned by the content. Pass entities and relationships when you can (caller-wins). You build the graph \u2014 the server does not extract it for you unless a self-host operator has configured a BYO extraction endpoint (then caller-passed graph still wins). On a multi-entity store, include at least one relationship connecting the entities, or the store is refused so isolated nodes never accumulate (set entitiesOnly for a deliberate lone entity); triples make edges impossible to omit.";
+var STORE_RELATIONSHIPS_DESC = 'Edges between entities; source and target must be entity names from this request. Pass entities and relationships when you can (caller-wins). You build the graph \u2014 the server does not extract it for you unless a self-host operator has configured a BYO extraction endpoint (then caller-passed graph still wins). On a multi-entity store, include at least one relationship connecting the entities, or the store is refused so isolated nodes never accumulate (set entitiesOnly for a deliberate lone entity); triples make edges impossible to omit. 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.';
+var STORE_TRIPLES_DESC = "Graph facts as subject\u2013relation\u2013object triples; each is materialized into the two entity nodes plus the edge that connects them, so a node cannot be added without its relationship. Use this (or entities + relationships) to populate the knowledge graph \u2014 for weak hosts triples make edges unavoidable. subject/object each have a name and a type (from the entity-type set); relation is a freeform label. Merged with any entities/relationships you also pass (caller-wins); duplicates within one call are collapsed.";
+var STORE_EVENT_TIME_DESC = '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.';
+var STORE_TOOL_DESC = "Store one concise factual memory with required topic and project metadata. When content names people, organizations, tools, places, events, or key concepts, pass entities and relationships when you can (caller-wins). You build the graph \u2014 the server does not extract it for you unless a self-host operator has configured a BYO extraction endpoint (then caller-passed graph still wins). On a multi-entity store, include at least one relationship connecting the entities, or the store is refused so isolated nodes never accumulate (set entitiesOnly for a deliberate lone entity); triples make edges impossible to omit. 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.";
+var SEARCH_LIMIT_DESC = "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.";
+var SEARCH_ENUMERATION_CONCEPT_DESC = '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.';
+var STRUCTURE_GRAPH_PROMPT_DESC = "Returns a prompt that extracts the graph fields (triples, or entities + relationships) to include in a store_memory call \u2014 run it with your own LLM, then add the JSON it returns to your store_memory arguments (you still supply content/topic/project). Useful when store_memory returns GRAPH_RELATIONSHIPS_REQUIRED, or for any content with graph-worthy facts. This prompt is executed by your agent, not the server.";
+function buildGraphStructuringPrompt(content) {
+  return [
+    "Read the content below and produce the GRAPH FIELDS to add to your store_memory call (you supply content/topic/project yourself). Output ONLY the JSON for those fields, no prose.",
+    "",
+    "Prefer triples \u2014 they make edges impossible to forget:",
+    '  { "triples": [ { "subject": { "name": "...", "type": "<TYPE>" }, "relation": "<UPPER_SNAKE>", "object": { "name": "...", "type": "<TYPE>" } } ] }',
+    'Equivalent shape: { "entities": [ { "name": "...", "type": "<TYPE>" } ], "relationships": [ { "source": "...", "target": "...", "type": "<UPPER_SNAKE>" } ] }',
+    "",
+    "<TYPE> is one of: PERSON, ORGANIZATION, CONCEPT, TOOL, LOCATION, EVENT.",
+    "relation/type is a freeform UPPER_SNAKE label (e.g. WORKS_AT, USES, OWNS, PART_OF, IS_A, CREATED_BY).",
+    "",
+    "Rules:",
+    "- Link every entity you emit with at least one non-self edge \u2014 isolated nodes never connect. If two are only loosely related, use RELATED_TO rather than leaving one unconnected.",
+    "- Do not invent facts beyond the content.",
+    "",
+    "Content:",
+    '"""',
+    content,
+    '"""'
+  ].join("\n");
+}
+function buildAgentSnippet() {
+  const targetLines = AGENT_TARGETS.map(
+    ({ tool, instructionsFile }) => `- ${tool} \u2192 ${instructionsFile}`
+  );
+  return [
+    "AI agent: install the global memory rules below \u2014 make no other changes.",
+    "",
+    "Choose the target file by the HOST tool you are running inside, NOT by which model you are. A Claude, GPT, or Gemini model running inside another agent (oh-my-pi, Cursor, Cline, \u2026) must write to THAT agent's file \u2014 never to Claude Code's ~/.claude/CLAUDE.md or its model provider's file. If you are not certain which file your tool uses, ask the user.",
+    "",
+    "Target file by tool:",
+    ...targetLines,
+    "",
+    "Conflict policy:",
+    "- If an existing `Persistent Memory` section references the `pyx-memory` MCP tools, REPLACE it with the version below \u2014 this is the newer canonical rule set for the same system, not a duplicate.",
+    "- If an existing `Persistent Memory` section uses a different memory tool, append this one underneath instead. Do not delete, rewrite, or summarize the other tool's instructions.",
+    "",
+    "Install only the section below, verbatim. After writing, tell the user which file you updated.",
+    "",
+    PERSISTENT_MEMORY_SECTION
+  ].join("\n");
+}
+
+export {
+  PYX_MEMORY_INSTRUCTIONS,
+  PERSISTENT_MEMORY_SECTION,
+  buildDesignGuide,
+  AGENT_TARGETS,
+  STORE_ENTITIES_DESC,
+  STORE_RELATIONSHIPS_DESC,
+  STORE_TRIPLES_DESC,
+  STORE_EVENT_TIME_DESC,
+  STORE_TOOL_DESC,
+  SEARCH_LIMIT_DESC,
+  SEARCH_ENUMERATION_CONCEPT_DESC,
+  STRUCTURE_GRAPH_PROMPT_DESC,
+  buildGraphStructuringPrompt,
+  buildAgentSnippet
+};

package/dist/{chunk-DKNGLNN4.mjs → chunk-ZCGJGI2O.mjs}

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