@pyxmate/memory 1.3.0 → 1.4.0

package/dist/agent-contract.d.ts

@@ -1,4 +1,4 @@
-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 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 once a fact is settled: corrections, bug fixes (root cause + fix), design/architecture decisions (with reasoning), integration/API/auth/endpoint details, gotchas, explicit preferences, and \"remember this\" requests \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 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-XHEVB23R.mjs";
+} from "./chunk-ML6VKYAL.mjs";
 export {
   AGENT_TARGETS,
   PERSISTENT_MEMORY_SECTION,

package/dist/{chunk-XHEVB23R.mjs → chunk-ML6VKYAL.mjs}

@@ -1,5 +1,5 @@
 // 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 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 once a fact is settled: corrections, bug fixes (root cause + fix), design/architecture decisions (with reasoning), integration/API/auth/endpoint details, gotchas, explicit preferences, and "remember this" requests \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 PERSISTENT_MEMORY_SECTION = [
   "## Persistent Memory",
   "",
@@ -142,7 +142,8 @@ function buildAgentSnippet() {
     ...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 a pyx-memory managed block (between `<!-- pyx-memory:begin \u2026 -->` and `<!-- pyx-memory:end -->`) is already present \u2014 `pyx-mem mcp install` may have written it \u2014 leave it exactly as-is and do NOT add a second copy.",
+    "- Else 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.",

package/dist/cli/pyx-mem.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import {
+  PERSISTENT_MEMORY_SECTION,
   buildDesignGuide
-} from "../chunk-XHEVB23R.mjs";
+} from "../chunk-ML6VKYAL.mjs";
 
 // src/cli/exit-codes.ts
 var EXIT = {
@@ -797,7 +798,7 @@ function createProxyServer(client, version, uploadLocalFile) {
   return server;
 }
 async function runMcpProxyServer(opts) {
-  const version = opts.version ?? (true ? "1.3.0" : "0.0.0-dev");
+  const version = opts.version ?? (true ? "1.4.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();
@@ -977,6 +978,149 @@ function indent(text) {
   return text.split("\n").map((line) => `  ${line}`).join("\n");
 }
 
+// src/cli/commands/memory-rules-merge.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, renameSync as renameSync2, statSync, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname2 } from "path";
+var RULES_BEGIN_MARKER = "<!-- pyx-memory:begin (managed by `pyx-mem mcp install`; edit outside these markers) -->";
+var RULES_END_MARKER = "<!-- pyx-memory:end -->";
+var BEGIN_MARKER_PREFIX = "<!-- pyx-memory:begin";
+var PM_HEADING_RE = /^ {0,3}##[ \t]+Persistent Memory[ \t]*$/;
+var H1_OR_H2_RE = /^ {0,3}#{1,2}[ \t]+\S/;
+var FENCE_RE = /^ {0,3}(`{3,}|~{3,})/;
+function fenceMask(lines) {
+  const mask = new Array(lines.length).fill(false);
+  let openIdx = -1;
+  let delim = "";
+  let openLen = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const fence = FENCE_RE.exec(lines[i] ?? "")?.[1];
+    if (!fence) continue;
+    if (openIdx === -1) {
+      openIdx = i;
+      delim = fence.charAt(0);
+      openLen = fence.length;
+      continue;
+    }
+    if (fence.charAt(0) === delim && fence.length >= openLen) {
+      for (let j = openIdx; j <= i; j++) mask[j] = true;
+      openIdx = -1;
+      delim = "";
+      openLen = 0;
+    }
+  }
+  return mask;
+}
+function nextH1OrH2(lines, mask, from) {
+  for (let i = from; i < lines.length; i++) {
+    const line = lines[i];
+    if (line !== void 0 && !mask[i] && H1_OR_H2_RE.test(line)) return i;
+  }
+  return lines.length;
+}
+function findCompleteManagedRange(lines, mask) {
+  let begin = -1;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line === void 0 || mask[i]) continue;
+    const t = line.trim();
+    if (begin === -1) {
+      if (t.startsWith(BEGIN_MARKER_PREFIX)) begin = i;
+    } else if (t === RULES_END_MARKER) {
+      return [begin, i + 1];
+    }
+  }
+  return null;
+}
+function findOrphanBeginLine(lines, mask) {
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line !== void 0 && !mask[i] && line.trim().startsWith(BEGIN_MARKER_PREFIX)) return i;
+  }
+  return -1;
+}
+function findLegacyPyxRange(lines, mask) {
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line === void 0 || mask[i] || !PM_HEADING_RE.test(line)) continue;
+    const end = nextH1OrH2(lines, mask, i + 1);
+    if (lines.slice(i, end).join("\n").toLowerCase().includes("pyx-memory")) return [i, end];
+  }
+  return null;
+}
+function spliceBlock(lines, from, toExclusive, blockLines) {
+  const before = lines.slice(0, from);
+  const after = lines.slice(toExclusive);
+  while (before.length && (before[before.length - 1] ?? "").trim() === "") before.pop();
+  while (after.length && (after[0] ?? "").trim() === "") after.shift();
+  const out = [...before];
+  if (out.length) out.push("");
+  out.push(...blockLines);
+  if (after.length) out.push("");
+  out.push(...after);
+  return out;
+}
+function joinWithTrailingNewline(lines, eol) {
+  const body = lines.join(eol);
+  return body.endsWith(eol) ? body : `${body}${eol}`;
+}
+function mergeMemoryRules(existing, section) {
+  if (section.includes(BEGIN_MARKER_PREFIX) || section.includes(RULES_END_MARKER)) {
+    throw new Error("pyx-memory rules section must not contain the managed markers.");
+  }
+  const eol = existing.includes("\r\n") ? "\r\n" : "\n";
+  const blockLines = [RULES_BEGIN_MARKER, ...section.split(/\r?\n/), RULES_END_MARKER];
+  const normalized = existing.replace(/\r\n/g, "\n");
+  if (normalized.trim().length === 0) {
+    return { content: joinWithTrailingNewline(blockLines, eol), action: "created" };
+  }
+  let lines = normalized.split("\n");
+  let mask = fenceMask(lines);
+  const complete = findCompleteManagedRange(lines, mask);
+  if (complete) {
+    const next2 = spliceBlock(lines, complete[0], complete[1], blockLines);
+    return { content: joinWithTrailingNewline(next2, eol), action: "updated" };
+  }
+  const orphan = findOrphanBeginLine(lines, mask);
+  if (orphan !== -1) {
+    lines = [...lines.slice(0, orphan), ...lines.slice(orphan + 1)];
+    mask = fenceMask(lines);
+  }
+  const legacy = findLegacyPyxRange(lines, mask);
+  if (legacy) {
+    const next2 = spliceBlock(lines, legacy[0], legacy[1], blockLines);
+    return { content: joinWithTrailingNewline(next2, eol), action: "updated" };
+  }
+  const next = spliceBlock(lines, lines.length, lines.length, blockLines);
+  return { content: joinWithTrailingNewline(next, eol), action: "appended" };
+}
+function writeMemoryRulesFile(opts) {
+  const { filePath, section } = opts;
+  const fileExists = existsSync2(filePath);
+  const existing = fileExists ? readFileSync2(filePath, "utf8") : "";
+  const { content, action } = mergeMemoryRules(existing, section);
+  if (content === existing) {
+    return {
+      action: "unchanged",
+      filePath,
+      message: `pyx-memory rules already current in ${filePath} (no changes written).
+`
+    };
+  }
+  const parent = dirname2(filePath);
+  if (!existsSync2(parent)) mkdirSync2(parent, { recursive: true });
+  const mode = fileExists ? statSync(filePath).mode & 511 : 420;
+  const tmpPath = `${filePath}.tmp`;
+  writeFileSync2(tmpPath, content, { mode });
+  renameSync2(tmpPath, filePath);
+  const verb = action === "created" ? "Wrote" : action === "appended" ? "Added" : "Updated";
+  return {
+    action,
+    filePath,
+    message: `${verb} the pyx-memory rules in ${filePath}.
+`
+  };
+}
+
 // src/cli/commands/mcp-install.ts
 var VALID_SCOPES = /* @__PURE__ */ new Set(["local", "user", "project"]);
 var SERVER_NAME = "pyx-memory";
@@ -1283,6 +1427,28 @@ function printHermesManualInstructions(remote) {
     ].join("\n")
   );
 }
+var RULES_FILE_TARGETS = {
+  "claude-code": [".claude", "CLAUDE.md"],
+  codex: [".codex", "AGENTS.md"],
+  "gemini-cli": [".gemini", "GEMINI.md"],
+  "oh-my-pi": [".omp", "agent", "RULES.md"]
+};
+function installMemoryRules(opts) {
+  const segs = RULES_FILE_TARGETS[opts.target];
+  if (!segs) return;
+  if (opts.noRules) {
+    process.stdout.write(
+      'Skipped writing the memory rules (--no-rules). The tools are installed, but the agent will reach for memory only when you ask; add the "## Persistent Memory" rules yourself to change that.\n'
+    );
+    return;
+  }
+  const home = opts._homeDir ?? homedir();
+  const result = writeMemoryRulesFile({
+    filePath: join(home, ...segs),
+    section: PERSISTENT_MEMORY_SECTION
+  });
+  process.stdout.write(result.message);
+}
 function validateScope(scope) {
   if (VALID_SCOPES.has(scope)) return true;
   process.stderr.write(`Error: invalid --scope \`${scope}\`. Expected: local | user | project.
@@ -1311,7 +1477,7 @@ function writeJsonAndReport(filePath, agentLabel, entry, opts = {}) {
 }
 
 // src/cli/commands/scaffold.ts
-import { existsSync as existsSync2, mkdirSync as mkdirSync2, statSync, writeFileSync as writeFileSync2 } from "fs";
+import { existsSync as existsSync3, 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:
@@ -1453,21 +1619,21 @@ function buildFiles(targetDir, appName) {
 function scaffoldCommand(args = {}) {
   const target = resolveTarget(args);
   if (target === null) return EXIT.USAGE;
-  if (existsSync2(target.targetDir) && !statSync(target.targetDir).isDirectory()) {
+  if (existsSync3(target.targetDir) && !statSync2(target.targetDir).isDirectory()) {
     process.stderr.write(`Error: target exists and is not a directory: ${target.targetDir}
 `);
     return EXIT.USAGE;
   }
-  mkdirSync2(target.targetDir, { recursive: true });
+  mkdirSync3(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)) {
+    if (existsSync3(file.path)) {
       skipped.push(relativePath);
       continue;
     }
-    writeFileSync2(file.path, file.contents, "utf8");
+    writeFileSync3(file.path, file.contents, "utf8");
     created.push(relativePath);
   }
   process.stdout.write(
@@ -1547,11 +1713,16 @@ Commands:
                                                updates; key stays in the OS keychain). Self-host:
                                                run 'login --endpoint <url>' first to point it at
                                                your own server.
-  mcp install <target> [--scope user|local|project] [--remote]
+  mcp install <target> [--scope user|local|project] [--remote] [--no-rules]
                                                Install pyx-memory MCP config for your AI agent. The
                                                config launches the hosted zero-touch thin proxy;
                                                --remote is an accepted no-op alias (the bundled
                                                stdio server was removed in v1.3.0).
+                                               For claude-code, codex, gemini-cli, and oh-my-pi it
+                                               also writes the always-on "## Persistent Memory" rules
+                                               into that tool's global instructions file (idempotent;
+                                               your other content is preserved) so memory fires by
+                                               default. Pass --no-rules to skip that write.
                                                Targets: claude-code, codex, cursor, cline, continue, windsurf, gemini-cli, pi, oh-my-pi, openclaw, hermes.
 
 Notes:
@@ -1620,7 +1791,7 @@ var INSTALL_TARGETS = {
   hermes: mcpInstallHermesCommand
 };
 var VALID_TARGETS = Object.keys(INSTALL_TARGETS);
-function runMcpInstall(target, scope, remote) {
+function runMcpInstall(target, scope, remote, noRules) {
   if (target === void 0 || !Object.hasOwn(INSTALL_TARGETS, target)) {
     process.stderr.write(
       `Error: unknown install target \`${target ?? ""}\`. Expected: ${VALID_TARGETS.join(", ")}.
@@ -1629,7 +1800,9 @@ function runMcpInstall(target, scope, remote) {
     return EXIT.USAGE;
   }
   const handler = INSTALL_TARGETS[target];
-  return handler({ scope, remote });
+  const code = handler({ scope, remote });
+  if (code === EXIT.OK) installMemoryRules({ target, noRules });
+  return code;
 }
 function runMcpCommand(parsed) {
   if (parsed.subcommand === void 0) {
@@ -1647,7 +1820,12 @@ function runMcpCommand(parsed) {
   if (parsed.subcommand === "install") {
     const target = parsed.positional[0];
     const scope = typeof parsed.flags.scope === "string" ? parsed.flags.scope : void 0;
-    return runMcpInstall(target, scope, parsed.flags.remote === true);
+    return runMcpInstall(
+      target,
+      scope,
+      parsed.flags.remote === true,
+      parsed.flags["no-rules"] === true
+    );
   }
   process.stderr.write(
     `Error: unknown subcommand \`mcp ${parsed.subcommand}\`. Run \`pyx-mem --help\`.

package/package.json

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