@pyxmate/memory 1.6.0 → 1.8.0

package/dist/agent-contract.d.ts

@@ -19,11 +19,11 @@ declare const AGENT_TARGETS: readonly [{
     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_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. Use specific durable entities; never a catch-all hub (\"me\", \"health\") linked to everything \u2014 bounded IS_A category nodes are the deliberate exception.";
 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 \u2014 a decision, not deliberation. Required: content, topic, project; default type is long-term (use episodic for a milestone/handoff snapshot, summary for a rollup). Entity-free memories are valid: omit graph fields, or set extractEntities:false, when there are no graph facts. When content does name people, organizations, tools, places, events, or key concepts, pass entities and relationships (caller-wins); on a multi-entity store include at least one relationship connecting them, or the store is refused so isolated nodes never accumulate (set entitiesOnly for a deliberate lone entity), and triples make edges impossible to omit. Relationships (edges) matter as much as entities because graph traversal needs edges to connect related memories. You build the graph \u2014 the server does not extract it unless a self-host operator has configured a BYO extraction endpoint (then caller-passed graph still wins).";
+declare const STORE_TOOL_DESC = "Store one concise factual memory \u2014 a decision, not deliberation. Required: content, topic, project; default type is long-term (use episodic for a milestone/handoff snapshot, summary for a rollup). Entity-free memories are valid: omit graph fields, or set extractEntities:false, when there are no graph facts. When content does name people, organizations, tools, places, events, or key concepts, pass entities and relationships (caller-wins); on a multi-entity store include at least one relationship connecting them, or the store is refused so isolated nodes never accumulate (set entitiesOnly for a deliberate lone entity), and triples make edges impossible to omit. Relationships (edges) matter as much as entities because graph traversal needs edges to connect related memories. You build the graph \u2014 the server does not extract it unless a self-host operator has configured a BYO extraction endpoint (then caller-passed graph still wins). Aggregate high-frequency streams (wearable/sensor samples, metrics) into the dated fact or summary they support (with eventTime) \u2014 never one memory per sample.";
 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.";

package/dist/agent-contract.mjs

@@ -13,7 +13,7 @@ import {
   buildAgentSnippet,
   buildDesignGuide,
   buildGraphStructuringPrompt
-} from "./chunk-6IYMLQO2.mjs";
+} from "./chunk-SVKIFOS5.mjs";
 export {
   AGENT_TARGETS,
   PERSISTENT_MEMORY_SECTION,

package/dist/{chunk-6IYMLQO2.mjs → chunk-SVKIFOS5.mjs}

@@ -35,9 +35,9 @@ var PERSISTENT_MEMORY_SECTION = [
   "- 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, raw logs, or step-by-step progress as it happens \u2014 a milestone or handoff snapshot (Trajectory, above) is the deliberate exception.",
+  "- Do not store ephemeral file contents, raw logs, or step-by-step progress as it happens \u2014 a milestone or handoff snapshot (Trajectory, above) is the deliberate exception. The same applies to high-frequency streams (wearable/health samples, sensor readings, metrics): store the dated fact or summary they support (with `eventTime`), never one memory \u2014 or one graph node \u2014 per sample; the raw series belongs in the product database.",
   '- 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.',
+  '- 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. Use specific durable entities ("sleep apnea", "morning run routine"); never a catch-all hub node ("me", "health", "work") linked to everything \u2014 a mega-hub degrades every traversal that touches it, and bounded `IS_A` category nodes (below) are the deliberate exception. 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");
@@ -60,6 +60,7 @@ function buildDesignGuide({ appName }) {
     "### 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.",
+    "- [ ] Raw high-frequency streams (sensor/wearable samples, metrics, event feeds) \u2014 aggregate into the dated fact or summary they support (with `eventTime`); never one memory or graph node per sample.",
     "- [ ] Secrets, credentials, payment data, private keys, or sensitive payloads unless your app has an explicit policy and encryption posture for them.",
     "",
     "### eventTime Rules",
@@ -71,6 +72,7 @@ function buildDesignGuide({ appName }) {
     "",
     "- [ ] 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.",
+    '- [ ] Use specific durable entities; never a catch-all hub node (a "user"/"health"/"company" node linked to everything) \u2014 bounded `IS_A` category nodes are the deliberate exception.',
     "- [ ] 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",
@@ -98,11 +100,11 @@ var AGENT_TARGETS = [
     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_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. Use specific durable entities; never a catch-all hub ("me", "health") linked to everything \u2014 bounded IS_A category nodes are the deliberate exception.';
 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 \u2014 a decision, not deliberation. Required: content, topic, project; default type is long-term (use episodic for a milestone/handoff snapshot, summary for a rollup). Entity-free memories are valid: omit graph fields, or set extractEntities:false, when there are no graph facts. When content does name people, organizations, tools, places, events, or key concepts, pass entities and relationships (caller-wins); on a multi-entity store include at least one relationship connecting them, or the store is refused so isolated nodes never accumulate (set entitiesOnly for a deliberate lone entity), and triples make edges impossible to omit. Relationships (edges) matter as much as entities because graph traversal needs edges to connect related memories. You build the graph \u2014 the server does not extract it unless a self-host operator has configured a BYO extraction endpoint (then caller-passed graph still wins).";
+var STORE_TOOL_DESC = "Store one concise factual memory \u2014 a decision, not deliberation. Required: content, topic, project; default type is long-term (use episodic for a milestone/handoff snapshot, summary for a rollup). Entity-free memories are valid: omit graph fields, or set extractEntities:false, when there are no graph facts. When content does name people, organizations, tools, places, events, or key concepts, pass entities and relationships (caller-wins); on a multi-entity store include at least one relationship connecting them, or the store is refused so isolated nodes never accumulate (set entitiesOnly for a deliberate lone entity), and triples make edges impossible to omit. Relationships (edges) matter as much as entities because graph traversal needs edges to connect related memories. You build the graph \u2014 the server does not extract it unless a self-host operator has configured a BYO extraction endpoint (then caller-passed graph still wins). Aggregate high-frequency streams (wearable/sensor samples, metrics) into the dated fact or summary they support (with eventTime) \u2014 never one memory per sample.";
 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.";
@@ -119,6 +121,7 @@ function buildGraphStructuringPrompt(content) {
     "",
     "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.",
+    '- Use specific durable entities; do not emit a catch-all node for the user or a broad life domain ("me", "health") \u2014 attach facts to the specific entities involved.',
     "- Do not invent facts beyond the content.",
     "",
     "Content:",

package/dist/cli/pyx-mem.mjs

@@ -2,7 +2,7 @@
 import {
   PERSISTENT_MEMORY_SECTION,
   buildDesignGuide
-} from "../chunk-6IYMLQO2.mjs";
+} from "../chunk-SVKIFOS5.mjs";
 
 // src/cli/exit-codes.ts
 var EXIT = {
@@ -798,7 +798,7 @@ function createProxyServer(client, version, uploadLocalFile) {
   return server;
 }
 async function runMcpProxyServer(opts) {
-  const version = opts.version ?? (true ? "1.6.0" : "0.0.0-dev");
+  const version = opts.version ?? (true ? "1.8.0" : "0.0.0-dev");
   const read = await opts.readCredentials();
   if (!read.ok) {
     const text = read.result.content.map((c) => c.type === "text" ? c.text : "").join(" ").trim();

package/dist/index.d.ts

@@ -1009,6 +1009,21 @@ interface CorrectionRecord {
     /** Overlap-coefficient score between the query `taskShape` and this row's `appliesWhen`. */
     score: number;
 }
+/**
+ * Rolling graph-traversal telemetry (in-process, since boot). Watches the
+ * engine re-review triggers: depth-2 getNeighbors p95 latency / result size
+ * (hub explosion) and getAllEdges job duration.
+ */
+interface GraphTelemetrySnapshot {
+    /** p95 latency (ms) of getNeighbors calls with depth >= 2; null until sampled. */
+    neighborsDepth2P95Ms: number | null;
+    /** p95 result node count of getNeighbors calls with depth >= 2; null until sampled. */
+    neighborsDepth2ResultP95: number | null;
+    /** Depth >= 2 samples in the rolling window (confidence for the p95s). */
+    neighborsDepth2SampleCount: number;
+    /** Duration (ms) of the most recent getAllEdges call; null until one ran. */
+    allEdgesLastMs: number | null;
+}
 interface MemoryStats {
     totalEntries: number;
     storageUsedBytes: number;
@@ -1022,6 +1037,8 @@ interface MemoryStats {
     graphRawEdgeCount?: number;
     /** Name of the active graph store ('neo4j', 'sqlite', or undefined if none). */
     graphStore?: string;
+    /** Graph traversal telemetry; undefined when no graph store is active. */
+    graphTelemetry?: GraphTelemetrySnapshot;
     /** Whether the memory service is connected. False when using DisabledMemory. */
     connected?: boolean;
 }
@@ -1465,4 +1482,4 @@ interface CreatePyxMemoryOptions {
 }
 declare function createPyxMemory(opts?: CreatePyxMemoryOptions): MemoryClient;
 
-export { type AgentId, type ApiResponse, type ConsolidationRunResult, type CorrectionInput, type CorrectionRecord, type CreatePyxMemoryOptions, DEFAULTS, DEPRECATED_RAG_STRATEGIES, DisabledMemory, type DroppedGraphRelationship, EmbeddingProviderName, type EnrichmentCallbacks, type EntityExtractionResult, type ExtendedMemoryInterface, type FetchCorrectionsInput, type GraphEnrichment, type GraphEnrichmentStatus, type GraphFailureMode, type GraphNode, type GraphRelationship, type GraphRepairResult, type GraphTraversalResult, type IngestEntity, type IngestErrorEvent, type IngestEvent, type IngestFileOptions, type IngestHeartbeatEvent, type IngestProgressEvent, type IngestRelationship, type IngestResultEvent, type IngestStage, type IngestionResult, type LineageParams, type LineageResult, type LineageVersion, MemoryClient, type MemoryClientOptions, type MemoryEntry, type MemoryIngestRequest, type MemoryInterface, type MemoryListParams, type MemoryListResult, type MemoryLogFilters, type MemorySearchParams, type MemorySearchResult, MemoryServerError, type MemoryStats, MemoryType, type MoveEntriesFilter, MoveFailureReason, type MoveResult, type MoveTarget, NamespaceIsolation, type PrincipalContext, RAGStrategy, type ReinforceParams, type ReinforceResult, type ReinforceSignal, SINGLE_TENANT_ID, SensitivityLevel, type SourceEvidence, type StoreInput, StoreTarget, type TemporalQueryFilters, type TenantScopeOptions, type Timestamp, type Topology, type TopologyExtractionProvider, type TopologyServiceVariant, VectorProvider, type VectorStatus, type WikiLintReport, createPyxMemory, mergeExtractedEntities, normalizeGraphLabel, normalizeNameKey };
+export { type AgentId, type ApiResponse, type ConsolidationRunResult, type CorrectionInput, type CorrectionRecord, type CreatePyxMemoryOptions, DEFAULTS, DEPRECATED_RAG_STRATEGIES, DisabledMemory, type DroppedGraphRelationship, EmbeddingProviderName, type EnrichmentCallbacks, type EntityExtractionResult, type ExtendedMemoryInterface, type FetchCorrectionsInput, type GraphEnrichment, type GraphEnrichmentStatus, type GraphFailureMode, type GraphNode, type GraphRelationship, type GraphRepairResult, type GraphTelemetrySnapshot, type GraphTraversalResult, type IngestEntity, type IngestErrorEvent, type IngestEvent, type IngestFileOptions, type IngestHeartbeatEvent, type IngestProgressEvent, type IngestRelationship, type IngestResultEvent, type IngestStage, type IngestionResult, type LineageParams, type LineageResult, type LineageVersion, MemoryClient, type MemoryClientOptions, type MemoryEntry, type MemoryIngestRequest, type MemoryInterface, type MemoryListParams, type MemoryListResult, type MemoryLogFilters, type MemorySearchParams, type MemorySearchResult, MemoryServerError, type MemoryStats, MemoryType, type MoveEntriesFilter, MoveFailureReason, type MoveResult, type MoveTarget, NamespaceIsolation, type PrincipalContext, RAGStrategy, type ReinforceParams, type ReinforceResult, type ReinforceSignal, SINGLE_TENANT_ID, SensitivityLevel, type SourceEvidence, type StoreInput, StoreTarget, type TemporalQueryFilters, type TenantScopeOptions, type Timestamp, type Topology, type TopologyExtractionProvider, type TopologyServiceVariant, VectorProvider, type VectorStatus, type WikiLintReport, createPyxMemory, mergeExtractedEntities, normalizeGraphLabel, normalizeNameKey };

package/package.json

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