@pyxmate/memory 1.8.0 → 1.9.0

package/dist/agent-contract.d.ts

@@ -1,4 +1,4 @@
-declare const PYX_MEMORY_INSTRUCTIONS = "Use pyx-memory for durable memory across sessions, proactively \u2014 do not wait to be told. SEARCH before assuming: at the start of a task, and before proposing an approach or re-deriving a past decision, search memory for the project and topic; resolve relative times (\"last year\", \"\uB450 \uB2EC \uC804\") to an absolute ISO-8601 anchorTime so results rank by proximity to that time. STORE when durable state settles \u2014 usually before your final response or handoff; if nothing durable changed, store nothing. Otherwise capture a fact (correction, bug fix + root cause, design/architecture decision + reasoning, integration/API/auth/endpoint detail, gotcha, preference, \"remember this\"), a reusable process once stable, a milestone snapshot (type episodic, not a running log), or a changed decision (store the new state with eventTime, never a silent overwrite, so lineage traces it) \u2014 concise facts not deliberation, each with topic and project. Pass eventTime (ISO-8601, when the fact took effect) for anything that can change or go stale; recency ordering, \"as of\" queries, and stale-vs-current resolution all key off it. After a memory informs your work, call reinforce so it stays in the quick/medium tiers (idle never revives it). When the user corrects you, call record_correction; before a task, call fetch_applicable_corrections (pyx never auto-applies them). When content names people, organizations, tools, places, events, or key concepts, pass entities and relationships \u2014 you build the graph, the server does not extract it; a multi-entity store with no connecting edge is refused. Match search effort to need: quick (default, strongest) for routine recall, deep for full/archived history; use lineage to trace how a fact changed. userId/teamId/agentId and callerAccessLevel are attribution filters and sensitivity redaction, not a security isolation boundary \u2014 for tenant/namespace/ReBAC detail see the installed Persistent Memory rule.";
+declare const PYX_MEMORY_INSTRUCTIONS = "Use pyx-memory for durable memory across sessions, proactively \u2014 do not wait to be told. SEARCH before assuming: at the start of a task, and before proposing an approach or re-deriving a past decision, search memory for the project and topic; resolve relative times (\"last year\", \"\uB450 \uB2EC \uC804\") to an absolute ISO-8601 anchorTime so results rank by proximity to that time. STORE when durable state settles \u2014 usually before your final response or handoff; if nothing durable changed, store nothing. Otherwise capture a fact (correction, bug fix + root cause, design/architecture decision + reasoning, integration/API/auth/endpoint detail, gotcha, preference, \"remember this\"), a reusable process once stable, a milestone snapshot (type episodic, not a running log), or a changed decision (store the new state with eventTime, never a silent overwrite, so lineage traces it) \u2014 concise facts not deliberation, each with topic and project. Pass eventTime (ISO-8601, when the fact took effect) for anything that can change or go stale; recency ordering, \"as of\" queries, and stale-vs-current resolution all key off it. After a memory informs your work, call reinforce so it stays in the quick/medium tiers (idle never revives it). When the user corrects you, call record_correction; before a task, call fetch_applicable_corrections (pyx never auto-applies them). When content names people, organizations, tools, places, events, or key concepts, pass entities and relationships \u2014 you build the graph, the server does not extract it; a multi-entity store with no connecting edge is refused. Match search effort to need: quick (default, strongest) for routine recall, deep for full/archived history; use lineage to trace how a fact changed. userId/teamId/agentId and callerAccessLevel are attribution filters and sensitivity redaction, not a security isolation boundary \u2014 tenant/namespace isolation is enforced server-side (namespaces + ReBAC grants; see docs/access-control.md).";
 declare const PERSISTENT_MEMORY_SECTION: string;
 declare function buildDesignGuide({ appName }: {
     appName: string;

package/dist/agent-contract.mjs

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

package/dist/{chunk-SVKIFOS5.mjs → chunk-AXH45N7T.mjs}

@@ -1,5 +1,5 @@
 // src/contract/index.ts
-var PYX_MEMORY_INSTRUCTIONS = `Use pyx-memory for durable memory across sessions, proactively \u2014 do not wait to be told. SEARCH before assuming: at the start of a task, and before proposing an approach or re-deriving a past decision, search memory for the project and topic; resolve relative times ("last year", "\uB450 \uB2EC \uC804") to an absolute ISO-8601 anchorTime so results rank by proximity to that time. STORE when durable state settles \u2014 usually before your final response or handoff; if nothing durable changed, store nothing. Otherwise capture a fact (correction, bug fix + root cause, design/architecture decision + reasoning, integration/API/auth/endpoint detail, gotcha, preference, "remember this"), a reusable process once stable, a milestone snapshot (type episodic, not a running log), or a changed decision (store the new state with eventTime, never a silent overwrite, so lineage traces it) \u2014 concise facts not deliberation, each with topic and project. Pass eventTime (ISO-8601, when the fact took effect) for anything that can change or go stale; recency ordering, "as of" queries, and stale-vs-current resolution all key off it. After a memory informs your work, call reinforce so it stays in the quick/medium tiers (idle never revives it). When the user corrects you, call record_correction; before a task, call fetch_applicable_corrections (pyx never auto-applies them). When content names people, organizations, tools, places, events, or key concepts, pass entities and relationships \u2014 you build the graph, the server does not extract it; a multi-entity store with no connecting edge is refused. Match search effort to need: quick (default, strongest) for routine recall, deep for full/archived history; use lineage to trace how a fact changed. userId/teamId/agentId and callerAccessLevel are attribution filters and sensitivity redaction, not a security isolation boundary \u2014 for tenant/namespace/ReBAC detail see the installed Persistent Memory rule.`;
+var PYX_MEMORY_INSTRUCTIONS = `Use pyx-memory for durable memory across sessions, proactively \u2014 do not wait to be told. SEARCH before assuming: at the start of a task, and before proposing an approach or re-deriving a past decision, search memory for the project and topic; resolve relative times ("last year", "\uB450 \uB2EC \uC804") to an absolute ISO-8601 anchorTime so results rank by proximity to that time. STORE when durable state settles \u2014 usually before your final response or handoff; if nothing durable changed, store nothing. Otherwise capture a fact (correction, bug fix + root cause, design/architecture decision + reasoning, integration/API/auth/endpoint detail, gotcha, preference, "remember this"), a reusable process once stable, a milestone snapshot (type episodic, not a running log), or a changed decision (store the new state with eventTime, never a silent overwrite, so lineage traces it) \u2014 concise facts not deliberation, each with topic and project. Pass eventTime (ISO-8601, when the fact took effect) for anything that can change or go stale; recency ordering, "as of" queries, and stale-vs-current resolution all key off it. After a memory informs your work, call reinforce so it stays in the quick/medium tiers (idle never revives it). When the user corrects you, call record_correction; before a task, call fetch_applicable_corrections (pyx never auto-applies them). When content names people, organizations, tools, places, events, or key concepts, pass entities and relationships \u2014 you build the graph, the server does not extract it; a multi-entity store with no connecting edge is refused. Match search effort to need: quick (default, strongest) for routine recall, deep for full/archived history; use lineage to trace how a fact changed. userId/teamId/agentId and callerAccessLevel are attribution filters and sensitivity redaction, not a security isolation boundary \u2014 tenant/namespace isolation is enforced server-side (namespaces + ReBAC grants; see docs/access-control.md).`;
 var PERSISTENT_MEMORY_SECTION = [
   "## Persistent Memory",
   "",
@@ -8,38 +8,38 @@ var PERSISTENT_MEMORY_SECTION = [
   "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.",
+  "- Before suggesting an approach, search for prior decisions that might 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.',
+  "- When investigating a bug, search for prior occurrences and fixes.",
+  '- 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, without excluding other results.',
+  "- Match search `effort` to risk: use `quick` for routine recall; use `deep` when quick returns nothing, when prior state may be archived/superseded, or when full history matters.",
+  '- To trace how a fact changed ("what did X use before Y", how it evolved), call `lineage` with `subject` + `relation` or an `entryId` instead of stitching together searches.',
+  "- Recalled memories reflect what was true when written \u2014 if one names a file, function, flag, or version, verify it still exists before acting on it.",
   "",
-  "Reinforce what you use:",
+  "Reinforce and correct:",
   "",
-  "- 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.",
+  "- After a retrieved memory actually informs your work (you cited it or acted on it), call `reinforce` on that memory. Recall keeps useful memories in the `quick`/`medium` tiers.",
+  "- When the user corrects a mistake, call `record_correction` with what was wrong, what to do instead, and when it applies.",
+  "- Before starting a task, call `fetch_applicable_corrections` with the task shape; pyx never auto-applies them, so decide which corrections fit.",
   "",
   "Store when durable state settles \u2014 usually before a final response or handoff. Treat that moment as a check, not an automatic write: sparse and high-value beats dense and noisy, so if nothing durable changed, store nothing. When it did, capture only what applies:",
   "",
-  '- Facts (default) \u2014 corrections and preferences; bug fixes with root cause and fix; architecture or design decisions with reasoning; integration details (API format, auth flow, endpoint or tool behavior); gotchas with what broke and the fix; explicit "remember this" requests. One fact per memory.',
-  "- Process (`type: long-term`) \u2014 a reusable workflow, convention, or playbook a fresh session should follow. Store it once it has stabilized or been adopted, not while you are still trying approaches.",
-  "- Trajectory (`type: episodic`) \u2014 only at a real milestone, handoff, or user-requested checkpoint: one dated snapshot of what changed, where it now stands, and the open frontier. Not a running log \u2014 do not store step-by-step progress or ordinary end-of-turn summaries; for a maintained project or entity rollup call `summarize_memory_entity` instead.",
-  "- Evolution \u2014 when a prior fact or decision changes, store the new state with its `eventTime` rather than overwriting the old one, so `lineage` can trace how and why it evolved. Route explicit user corrections through `record_correction`; keep durable user or project traits current with `upsert_user_profile`.",
+  '- Facts (default) \u2014 corrections/preferences; bug fixes with root cause and fix; architecture/design decisions with reasoning; integration/API/auth/endpoint details; gotchas with what broke and the fix; explicit "remember this" requests. One fact per memory.',
+  "- Process (`type: long-term`) \u2014 a reusable workflow, convention, or playbook a fresh session should follow. Store it once stabilized or adopted.",
+  "- Trajectory (`type: episodic`) \u2014 only at a real milestone, handoff, or user-requested checkpoint: one dated snapshot of what changed, where it stands, and the open frontier. Not a running log.",
+  "- Evolution \u2014 when a prior fact or decision changes, store the new state with its `eventTime` rather than overwriting the old one, so `lineage` can trace how and why it evolved. Route explicit corrections through `record_correction`.",
   "",
   "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, 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. 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."
+  "- Keep one memory per concept; do not bundle unrelated facts.",
+  "- Do not store ephemeral file contents, raw logs, or step-by-step progress as it happens. High-frequency streams (wearable/health samples, sensor readings, metrics) must be aggregated into the dated fact or summary they support (with `eventTime`), never stored as one memory or graph node per sample.",
+  '- Pass `eventTime` (ISO-8601, when the fact happened or took effect) for facts 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 resolution key off it.',
+  "- Graph is a retrieval structure. When content names people, organizations, tools, places, events, or key concepts, pass `entities` and `relationships` when you can (caller-wins). On a multi-entity store, include at least one relationship connecting them, or use `triples` so edges are explicit. Relationships matter as much as entities for traversal. Entity-free memories are valid.",
+  '- Use specific durable entities ("sleep apnea", "morning run routine"). Never create a catch-all hub node ("me", "health", "work") linked to everything; mega-hubs degrade traversal. Bounded `IS_A` category nodes are the exception.',
+  '- For countable categories the user may later enumerate ("fitness classes", "streaming services", "pets"), add a canonical category `CONCEPT` node and an `IS_A` edge from each member to it (`"yoga"` IS_A `"fitness classes"`).',
+  "- 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";

package/dist/cli/pyx-mem.mjs

@@ -2,7 +2,7 @@
 import {
   PERSISTENT_MEMORY_SECTION,
   buildDesignGuide
-} from "../chunk-SVKIFOS5.mjs";
+} from "../chunk-AXH45N7T.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.8.0" : "0.0.0-dev");
+  const version = opts.version ?? (true ? "1.9.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();
@@ -832,34 +832,9 @@ async function runMcpProxyServer(opts) {
   }
 }
 
-// src/cli/commands/mcp.ts
-async function mcpCommand() {
-  const readCredentials = createReadCredentials(() => getDefaultKeychain());
-  const onStdinEnd = new Promise((resolve3) => {
-    process.stdin.once("end", resolve3);
-    process.stdin.once("close", resolve3);
-  });
-  try {
-    await Promise.race([runMcpProxyServer({ readCredentials }), onStdinEnd]);
-    return EXIT.OK;
-  } catch (err) {
-    process.stderr.write(`Internal error: ${err instanceof Error ? err.message : String(err)}
-`);
-    return EXIT.USAGE;
-  }
-}
-function resolveMcpMode(flags) {
-  if (flags.bundled === true) {
-    return {
-      ok: false,
-      error: "The bundled stdio MCP server was removed in v1.3.0. `pyx-mem mcp` now uses the hosted zero-touch path (server-owned tools + instructions; your key stays in the OS keychain). Drop `--bundled`. For a self-hosted server, point at it with `pyx-mem login --endpoint <url>` first."
-    };
-  }
-  return { ok: true };
-}
-
 // src/cli/commands/mcp-install.ts
 import { spawnSync as nodeSpawnSync } from "child_process";
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
 import { homedir } from "os";
 import { join } from "path";
 
@@ -1047,6 +1022,11 @@ function findLegacyPyxRange(lines, mask) {
   }
   return null;
 }
+function hasPyxMemoryRules(content) {
+  const lines = content.replace(/\r\n/g, "\n").split("\n");
+  const mask = fenceMask(lines);
+  return findCompleteManagedRange(lines, mask) !== null || findOrphanBeginLine(lines, mask) !== -1 || findLegacyPyxRange(lines, mask) !== null;
+}
 function spliceBlock(lines, from, toExclusive, blockLines) {
   const before = lines.slice(0, from);
   const after = lines.slice(toExclusive);
@@ -1449,6 +1429,24 @@ function installMemoryRules(opts) {
   });
   process.stdout.write(result.message);
 }
+function reconcileMemoryRules(opts = {}) {
+  const home = opts._homeDir ?? homedir();
+  for (const segs of Object.values(RULES_FILE_TARGETS)) {
+    const filePath = join(home, ...segs);
+    try {
+      if (!existsSync3(filePath)) continue;
+      if (!hasPyxMemoryRules(readFileSync3(filePath, "utf8"))) continue;
+      const result = writeMemoryRulesFile({ filePath, section: PERSISTENT_MEMORY_SECTION });
+      if (result.action !== "unchanged") {
+        process.stderr.write(
+          `pyx-memory: refreshed the "## Persistent Memory" rules in ${filePath}
+`
+        );
+      }
+    } catch {
+    }
+  }
+}
 function validateScope(scope) {
   if (VALID_SCOPES.has(scope)) return true;
   process.stderr.write(`Error: invalid --scope \`${scope}\`. Expected: local | user | project.
@@ -1476,8 +1474,35 @@ function writeJsonAndReport(filePath, agentLabel, entry, opts = {}) {
   return result.exitCode;
 }
 
+// src/cli/commands/mcp.ts
+async function mcpCommand() {
+  reconcileMemoryRules();
+  const readCredentials = createReadCredentials(() => getDefaultKeychain());
+  const onStdinEnd = new Promise((resolve3) => {
+    process.stdin.once("end", resolve3);
+    process.stdin.once("close", resolve3);
+  });
+  try {
+    await Promise.race([runMcpProxyServer({ readCredentials }), onStdinEnd]);
+    return EXIT.OK;
+  } catch (err) {
+    process.stderr.write(`Internal error: ${err instanceof Error ? err.message : String(err)}
+`);
+    return EXIT.USAGE;
+  }
+}
+function resolveMcpMode(flags) {
+  if (flags.bundled === true) {
+    return {
+      ok: false,
+      error: "The bundled stdio MCP server was removed in v1.3.0. `pyx-mem mcp` now uses the hosted zero-touch path (server-owned tools + instructions; your key stays in the OS keychain). Drop `--bundled`. For a self-hosted server, point at it with `pyx-mem login --endpoint <url>` first."
+    };
+  }
+  return { ok: true };
+}
+
 // src/cli/commands/scaffold.ts
-import { existsSync as existsSync3, mkdirSync as mkdirSync3, statSync as statSync2, writeFileSync as writeFileSync3 } from "fs";
+import { existsSync as existsSync4, mkdirSync as mkdirSync3, statSync as statSync2, writeFileSync as writeFileSync3 } 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:
@@ -1619,7 +1644,7 @@ function buildFiles(targetDir, appName) {
 function scaffoldCommand(args = {}) {
   const target = resolveTarget(args);
   if (target === null) return EXIT.USAGE;
-  if (existsSync3(target.targetDir) && !statSync2(target.targetDir).isDirectory()) {
+  if (existsSync4(target.targetDir) && !statSync2(target.targetDir).isDirectory()) {
     process.stderr.write(`Error: target exists and is not a directory: ${target.targetDir}
 `);
     return EXIT.USAGE;
@@ -1629,7 +1654,7 @@ function scaffoldCommand(args = {}) {
   const skipped = [];
   for (const file of buildFiles(target.targetDir, target.appName)) {
     const relativePath = basename2(file.path);
-    if (existsSync3(file.path)) {
+    if (existsSync4(file.path)) {
       skipped.push(relativePath);
       continue;
     }

package/package.json

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