@pyxmate/memory 1.22.3 → 1.23.1

package/dist/agent-contract.d.ts

@@ -1,6 +1,7 @@
-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 PYX_MEMORY_INSTRUCTIONS = "Use pyx-memory for durable memory across sessions, proactively \u2014 do not wait to be told. It is the memory of record: a host's built-in memory (e.g. MEMORY.md) never replaces it. At the start of each conversation, load the tools (even if deferred) and call get_memory_rules; its rules are current and supersede any older pasted copy. 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. 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 decision + reasoning, integration/API 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. When the user corrects you, call record_correction; before a task, call fetch_applicable_corrections. 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, not a security isolation boundary.";
 declare const PYX_MEMORY_COMPANION_CORE_INSTRUCTIONS = "Use pyx-memory for durable memory across sessions, proactively \u2014 do not wait to be told. SEARCH (search_memories) before assuming: at the start of a task, and before 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. Match search effort to need: quick (default, strongest) for routine recall, deep for full/archived history. STORE (store_memory) when durable state settles \u2014 usually before your final response; if nothing durable changed, store nothing. Capture concise facts, not deliberation \u2014 a correction, bug fix + root cause, decision + reasoning, integration detail, gotcha, preference, or an explicit \"remember this\" \u2014 each with topic and project. Pass eventTime (ISO-8601, when the fact took effect) for anything that can change or go stale; recency ordering and stale-vs-current resolution key off it. When content names people, organizations, tools, places, events, or key concepts, pass entities and relationships \u2014 you build the graph; a multi-entity store with no connecting edge is refused. Recalled memories reflect what was true when written \u2014 verify named files, flags, and versions before acting.";
 declare const PERSISTENT_MEMORY_SECTION: string;
+declare const PASTE_MEMORY_RULES: string;
 declare function buildDesignGuide({ appName }: {
     appName: string;
 }): string;
@@ -38,4 +39,4 @@ declare const STRUCTURE_GRAPH_PROMPT_DESC = "Returns a prompt that extracts the
 declare function buildGraphStructuringPrompt(content: string): string;
 declare function buildAgentSnippet(): string;
 
-export { AGENT_TARGETS, PERSISTENT_MEMORY_SECTION, PYX_MEMORY_COMPANION_CORE_INSTRUCTIONS, 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 };
+export { AGENT_TARGETS, PASTE_MEMORY_RULES, PERSISTENT_MEMORY_SECTION, PYX_MEMORY_COMPANION_CORE_INSTRUCTIONS, 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

@@ -1,5 +1,6 @@
 import {
   AGENT_TARGETS,
+  PASTE_MEMORY_RULES,
   PERSISTENT_MEMORY_SECTION,
   PYX_MEMORY_COMPANION_CORE_INSTRUCTIONS,
   PYX_MEMORY_INSTRUCTIONS,
@@ -14,9 +15,10 @@ import {
   buildAgentSnippet,
   buildDesignGuide,
   buildGraphStructuringPrompt
-} from "./chunk-EZERG25I.mjs";
+} from "./chunk-QD7G23CN.mjs";
 export {
   AGENT_TARGETS,
+  PASTE_MEMORY_RULES,
   PERSISTENT_MEMORY_SECTION,
   PYX_MEMORY_COMPANION_CORE_INSTRUCTIONS,
   PYX_MEMORY_INSTRUCTIONS,

package/dist/{chunk-QWLTZIIK.mjs → chunk-7YHCNO3N.mjs}

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

package/dist/{chunk-BUKDWHTY.mjs → chunk-C46EE5BH.mjs}

@@ -256,6 +256,11 @@ var DATA_PLANE_OPERATION_COVERAGE = {
     reasonCode: "nonchargeable_operation",
     reason: "status is nonchargeable and must bypass data-plane reservation"
   },
+  "mcp:get_memory_rules": {
+    support: "not_execution_ready",
+    reasonCode: "nonchargeable_operation",
+    reason: "the rules text is nonchargeable and must bypass data-plane reservation"
+  },
   "mcp:get_user_profile": { support: "sqlite_atomic_one_step" },
   "mcp:upsert_user_profile": { support: "sqlite_atomic_one_step" },
   "mcp:record_correction": { support: "sqlite_atomic_one_step" },

package/dist/{chunk-EZERG25I.mjs → chunk-QD7G23CN.mjs}

@@ -1,10 +1,10 @@
 // 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 tenant/namespace isolation is enforced server-side (namespaces + ReBAC grants; see docs/access-control.md).`;
+var PYX_MEMORY_INSTRUCTIONS = `Use pyx-memory for durable memory across sessions, proactively \u2014 do not wait to be told. It is the memory of record: a host's built-in memory (e.g. MEMORY.md) never replaces it. At the start of each conversation, load the tools (even if deferred) and call get_memory_rules; its rules are current and supersede any older pasted copy. 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. 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 decision + reasoning, integration/API 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. When the user corrects you, call record_correction; before a task, call fetch_applicable_corrections. 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, not a security isolation boundary.`;
 var PYX_MEMORY_COMPANION_CORE_INSTRUCTIONS = `Use pyx-memory for durable memory across sessions, proactively \u2014 do not wait to be told. SEARCH (search_memories) before assuming: at the start of a task, and before 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. Match search effort to need: quick (default, strongest) for routine recall, deep for full/archived history. STORE (store_memory) when durable state settles \u2014 usually before your final response; if nothing durable changed, store nothing. Capture concise facts, not deliberation \u2014 a correction, bug fix + root cause, decision + reasoning, integration detail, gotcha, preference, or an explicit "remember this" \u2014 each with topic and project. Pass eventTime (ISO-8601, when the fact took effect) for anything that can change or go stale; recency ordering and stale-vs-current resolution key off it. When content names people, organizations, tools, places, events, or key concepts, pass entities and relationships \u2014 you build the graph; a multi-entity store with no connecting edge is refused. Recalled memories reflect what was true when written \u2014 verify named files, flags, and versions before acting.`;
 var PERSISTENT_MEMORY_SECTION = [
   "## Persistent Memory",
   "",
-  "Use the configured `pyx-memory` MCP tools for durable memory across conversations.",
+  "Use the configured `pyx-memory` MCP tools as your memory of record across conversations; a host's built-in memory (e.g. `MEMORY.md`) never replaces them. Load them first if deferred.",
   "",
   "Search before assuming:",
   "",
@@ -28,7 +28,7 @@ var PERSISTENT_MEMORY_SECTION = [
   "Store when durable state settles, usually before a final response/handoff; if nothing durable changed, store nothing. Capture:",
   "",
   '- Facts (default) \u2014 one correction/preference, root-cause fix, reasoned design decision, integration detail, gotcha, or explicit "remember this" request per memory.',
-  "- Process (`type: long-term`) \u2014 a reusable workflow, convention, or playbook a fresh session should follow. Store it once stabilized or adopted.",
+  "- Process (`type: long-term`) \u2014 a reusable workflow, convention, or playbook a fresh session should follow, 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.",
   "- Ordinary conversational facts omit `id` and evolve through new entries with `eventTime`. Only application-owned canonical mirrors may reuse an app-supplied stable `id` with `metadata.dbRef.revision`. Revisions are opaque; retry with the same stable `id`, opaque revision, and byte-exact identical payload. Never invent, randomize, or timestamp-suffix IDs; replay stale snapshots or manifests; or use store-new plus delete-old. On `revision_reuse_conflict`, reread the authoritative source; do not mint a new ID or revision.",
   "",
@@ -36,15 +36,19 @@ var PERSISTENT_MEMORY_SECTION = [
   "",
   "- Always include `topic` and `project`.",
   "- Store concise facts and decisions, not deliberation.",
-  "- Keep one memory per concept; do not bundle unrelated facts.",
   "- Do not store ephemeral files, raw logs, or progress. Aggregate high-frequency streams into a dated fact/summary with `eventTime`; never one memory or graph node per sample.",
   "- Pass `eventTime` (ISO-8601, when a changeable/stale fact happened/took effect); recency/as-of/stale-vs-current key off it.",
   "- Graph is for retrieval. For named people, organizations, tools, places, events, or concepts, pass `entities` + `relationships` (caller-wins); connect multi-entity stores with a relationship or `triples`. Relationships matter as much as entities. Entity-free memories are valid.",
   '- Use specific durable entities, never catch-all hubs ("me", "health"); bounded `IS_A` categories are the exception.',
   '- For countable categories the user may later enumerate, add a canonical category `CONCEPT` node and an `IS_A` edge from each member to it (`"yoga"` IS_A `"fitness classes"`).',
   "- Taxonomy: when a store response reports unnamed clusters, call get_taxonomy_state and name each via name_cluster (short, domain-true, user's language); rename only when composition clearly changed.",
-  "- Ingest documents/images only when they are worth persisting; images require a short description so they are searchable.",
-  "- Before ingesting docx/xlsx/pptx, prefer pre-extracting to `.md`; headings preserve section context."
+  "- Ingest documents/images only when worth persisting; images need a short description to be searchable.",
+  "- Before ingesting docx/xlsx/pptx, pre-extract to `.md`; headings keep section context."
+].join("\n");
+var PASTE_MEMORY_RULES = [
+  "## Persistent Memory",
+  "",
+  "Use the configured `pyx-memory` MCP tools as your memory of record across conversations; a host's built-in memory never replaces them. At the start of every conversation, load them (even if deferred), call `get_memory_rules`, and follow the rules it returns \u2014 they are always current."
 ].join("\n");
 function buildDesignGuide({ appName }) {
   const name = appName.trim() || "your app";
@@ -154,7 +158,7 @@ function buildAgentSnippet() {
     "",
     "Install only the section below, verbatim. After writing, tell the user which file you updated.",
     "",
-    PERSISTENT_MEMORY_SECTION
+    PASTE_MEMORY_RULES
   ].join("\n");
 }
 
@@ -162,6 +166,7 @@ export {
   PYX_MEMORY_INSTRUCTIONS,
   PYX_MEMORY_COMPANION_CORE_INSTRUCTIONS,
   PERSISTENT_MEMORY_SECTION,
+  PASTE_MEMORY_RULES,
   buildDesignGuide,
   AGENT_TARGETS,
   STORE_ENTITIES_DESC,

package/dist/{chunk-HVJZDJGH.mjs → chunk-SGL73IY5.mjs}

@@ -2,7 +2,7 @@ import {
   RAGStrategy,
   assertGraphExtractionPayload,
   mergeExtractedEntities
-} from "./chunk-BUKDWHTY.mjs";
+} from "./chunk-C46EE5BH.mjs";
 
 // ../client/src/disabled-memory.ts
 var DEFAULT_PAGE_LIMIT = 20;

package/dist/cli/pyx-mem.mjs

@@ -2,7 +2,7 @@
 import {
   PERSISTENT_MEMORY_SECTION,
   buildDesignGuide
-} from "../chunk-EZERG25I.mjs";
+} from "../chunk-QD7G23CN.mjs";
 import {
   MEMORY_PROJECT_LABEL_MAX_CHARS,
   TAXONOMY_MAX_CATEGORIES,
@@ -10,7 +10,7 @@ import {
   TAXONOMY_MAX_SAMPLE_TOPICS,
   TAXONOMY_MAX_TOP_ENTITIES
 } from "../chunk-KZKGRND2.mjs";
-import "../chunk-BUKDWHTY.mjs";
+import "../chunk-C46EE5BH.mjs";
 
 // src/cli/exit-codes.ts
 var EXIT = {
@@ -2223,7 +2223,7 @@ function createProxyServer(client, version, uploadLocalFile) {
   return server;
 }
 async function runMcpProxyServer(opts) {
-  const version = opts.version ?? (true ? "1.22.3" : "0.0.0-dev");
+  const version = opts.version ?? (true ? "1.23.1" : "0.0.0-dev");
   const read = await opts.readCredentials();
   if (!read.ok) {
     throw new Error(
@@ -2257,7 +2257,9 @@ async function runMcpProxyServer(opts) {
     const closed = new Promise((resolve3) => {
       transport.onclose = () => resolve3();
     });
+    process.stdin.once("end", () => void transport.close());
     await server.connect(transport);
+    void opts.onConnected?.(client);
     await closed;
   } finally {
     await client.close().catch(() => {
@@ -2267,7 +2269,7 @@ async function runMcpProxyServer(opts) {
 
 // src/cli/commands/mcp-install.ts
 import { spawnSync as nodeSpawnSync } from "child_process";
-import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
+import { existsSync as existsSync3 } from "fs";
 import { homedir as homedir2 } from "os";
 import { join as join2 } from "path";
 
@@ -2387,7 +2389,20 @@ function indent(text) {
 }
 
 // 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 { randomUUID as randomUUID4 } from "crypto";
+import {
+  chmodSync,
+  existsSync as existsSync2,
+  linkSync,
+  lstatSync,
+  mkdirSync as mkdirSync2,
+  readFileSync as readFileSync2,
+  realpathSync,
+  renameSync as renameSync2,
+  rmSync,
+  statSync,
+  writeFileSync as writeFileSync2
+} from "fs";
 import { dirname as dirname3 } 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 -->";
@@ -2395,6 +2410,15 @@ 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,})/;
+var CLOSING_FENCE_RE = /^ {0,3}(`{3,}|~{3,})[ \t]*$/;
+var BEGIN_MARKER_RE = /^ {0,3}<!-- pyx-memory:begin(?:[ \t][^>]*)?-->[ \t]*$/;
+var END_MARKER_RE = /^ {0,3}<!-- pyx-memory:end -->[ \t]*$/;
+function isBeginMarker(line) {
+  return BEGIN_MARKER_RE.test(line);
+}
+function isEndMarker(line) {
+  return END_MARKER_RE.test(line);
+}
 function fenceMask(lines) {
   const mask = new Array(lines.length).fill(false);
   let openIdx = -1;
@@ -2409,7 +2433,7 @@ function fenceMask(lines) {
       openLen = fence.length;
       continue;
     }
-    if (fence.charAt(0) === delim && fence.length >= openLen) {
+    if (CLOSING_FENCE_RE.test(lines[i] ?? "") && fence.charAt(0) === delim && fence.length >= openLen) {
       for (let j = openIdx; j <= i; j++) mask[j] = true;
       openIdx = -1;
       delim = "";
@@ -2430,36 +2454,29 @@ function findCompleteManagedRange(lines, mask) {
   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];
-    }
+    if (isBeginMarker(line)) begin = i;
+    else if (begin !== -1 && isEndMarker(line)) return [begin, i + 1];
   }
   return null;
 }
-function findOrphanBeginLine(lines, mask) {
+function findBeginLines(lines, mask) {
+  const found = [];
   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;
+    if (line !== void 0 && !mask[i] && isBeginMarker(line)) found.push(i);
   }
-  return -1;
+  return found;
 }
 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];
+    const own = lines.slice(i, end).filter((l, k) => !mask[i + k] && !isBeginMarker(l) && !isEndMarker(l));
+    if (own.join("\n").toLowerCase().includes("pyx-memory")) return [i, end];
   }
   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);
@@ -2476,7 +2493,13 @@ function joinWithTrailingNewline(lines, eol) {
   const body = lines.join(eol);
   return body.endsWith(eol) ? body : `${body}${eol}`;
 }
+var BOM = "\uFEFF";
 function mergeMemoryRules(existing, section) {
+  const bom = existing.startsWith(BOM) ? BOM : "";
+  const merged = mergeBody(existing.slice(bom.length), section);
+  return { ...merged, content: bom + merged.content };
+}
+function mergeBody(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.");
   }
@@ -2493,9 +2516,9 @@ function mergeMemoryRules(existing, section) {
     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)];
+  const orphans = new Set(findBeginLines(lines, mask));
+  if (orphans.size > 0) {
+    lines = lines.filter((_, i) => !orphans.has(i));
     mask = fenceMask(lines);
   }
   const legacy = findLegacyPyxRange(lines, mask);
@@ -2506,12 +2529,53 @@ function mergeMemoryRules(existing, section) {
   const next = spliceBlock(lines, lines.length, lines.length, blockLines);
   return { content: joinWithTrailingNewline(next, eol), action: "appended" };
 }
+function refreshMemoryRules(file, section) {
+  const bom = file.startsWith(BOM) ? BOM : "";
+  const refreshed = refreshBody(file.slice(bom.length), section);
+  return refreshed === null ? null : bom + refreshed;
+}
+function refreshBody(existing, section) {
+  const lines = existing.replace(/\r\n/g, "\n").split("\n");
+  const complete = findCompleteManagedRange(lines, fenceMask(lines));
+  if (!complete) return null;
+  const [first, last] = [complete[0], complete[1] - 1];
+  const starts = [0];
+  for (let i = 0; i < existing.length; i++) if (existing[i] === "\n") starts.push(i + 1);
+  const from = starts[first] ?? 0;
+  const lastStart = starts[last] ?? 0;
+  const to = lastStart + (lines[last] ?? "").length;
+  const eol = existing.slice(from).match(/\r?\n/)?.[0] ?? "\n";
+  const block = [RULES_BEGIN_MARKER, ...section.split(/\r?\n/), RULES_END_MARKER].join(eol);
+  return existing.slice(0, from) + block + existing.slice(to);
+}
+function changedDuringWrite(filePath) {
+  return new Error(`${filePath} changed while updating the pyx-memory rules; retry.`);
+}
+function readUtf8Strict(path) {
+  try {
+    return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(readFileSync2(path));
+  } catch (err) {
+    if (err instanceof TypeError) {
+      throw new Error(`${path} is not valid UTF-8; the pyx-memory rules were not changed.`);
+    }
+    throw err;
+  }
+}
 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) {
+  if (!fileExists && lstatSync(filePath, { throwIfNoEntry: false })?.isSymbolicLink()) {
+    throw new Error(`${filePath} is a broken link; fix or remove it, then retry.`);
+  }
+  const target = fileExists ? realpathSync(filePath) : filePath;
+  const existing = fileExists ? readUtf8Strict(target) : "";
+  let merged = null;
+  if (!opts.refreshOnly) merged = mergeMemoryRules(existing, section);
+  else {
+    const content = refreshMemoryRules(existing, section);
+    if (content !== null) merged = { content, action: "updated" };
+  }
+  if (merged === null || merged.content === existing) {
     return {
       action: "unchanged",
       filePath,
@@ -2519,15 +2583,32 @@ function writeMemoryRulesFile(opts) {
 `
     };
   }
-  const parent = dirname3(filePath);
+  const parent = dirname3(target);
   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";
+  const mode = fileExists ? statSync(target).mode & 511 : 420;
+  const tmpPath = `${target}.${process.pid}.${randomUUID4()}.tmp`;
+  try {
+    writeFileSync2(tmpPath, merged.content, { mode });
+    chmodSync(tmpPath, mode);
+    if (fileExists) {
+      if (readUtf8Strict(target) !== existing) throw changedDuringWrite(filePath);
+      renameSync2(tmpPath, target);
+    } else {
+      try {
+        linkSync(tmpPath, target);
+      } catch (err) {
+        if (err.code === "EEXIST") throw changedDuringWrite(filePath);
+        throw err;
+      }
+      rmSync(tmpPath);
+    }
+  } catch (err) {
+    rmSync(tmpPath, { force: true });
+    throw err;
+  }
+  const verb = merged.action === "created" ? "Wrote" : merged.action === "appended" ? "Added" : "Updated";
   return {
-    action,
+    action: merged.action,
     filePath,
     message: `${verb} the pyx-memory rules in ${filePath}.
 `
@@ -2591,17 +2672,26 @@ function mcpInstallCodexCommand(opts = {}) {
   const remote = opts.remote ?? false;
   const spawnSync = opts._spawnSync ?? nodeSpawnSync;
   const home = opts._homeDir ?? homedir2();
+  const codexHome = (opts._env ?? process.env).CODEX_HOME;
   const probe = spawnSync("codex", ["--version"], { stdio: "pipe" });
   if (probe.error || probe.status !== 0) {
-    printCodexManualInstructions(home, remote);
+    printCodexManualInstructions(home, remote, codexHome);
     return EXIT.OK;
   }
-  const cmd = ["mcp", "add", SERVER_NAME, "--", "pyx-mem", ...pyxMemArgs(remote)];
+  const cmd = [
+    "mcp",
+    "add",
+    SERVER_NAME,
+    ...codexHome ? ["--env", `CODEX_HOME=${codexHome}`] : [],
+    "--",
+    "pyx-mem",
+    ...pyxMemArgs(remote)
+  ];
   const res = spawnSync("codex", cmd, { stdio: "inherit" });
   if (res.status !== 0) {
     process.stderr.write(`\`codex ${cmd.join(" ")}\` exited with code ${res.status ?? "null"}.
 `);
-    printCodexManualInstructions(home, remote);
+    printCodexManualInstructions(home, remote, codexHome);
     return EXIT.USAGE;
   }
   process.stdout.write(
@@ -2611,20 +2701,21 @@ Restart Codex CLI to make the tools available. No API key was written to config.
   );
   return EXIT.OK;
 }
-function printCodexManualInstructions(home, remote) {
-  const configPath = join2(home, ".codex", "config.toml");
+function printCodexManualInstructions(home, remote, codexHome) {
+  const configPath = join2(codexHome ?? join2(home, ".codex"), "config.toml");
   process.stdout.write(
     [
       "The `codex` CLI is not on PATH, or the install command failed.",
       "",
       "Run this once Codex CLI is installed:",
-      `  codex mcp add ${SERVER_NAME} -- pyx-mem ${pyxMemArgs(remote).join(" ")}`,
+      `  codex mcp add ${SERVER_NAME}${codexHome ? ` --env ${JSON.stringify(`CODEX_HOME=${codexHome}`)}` : ""} -- pyx-mem ${pyxMemArgs(remote).join(" ")}`,
       "",
       `Or add this section manually to ${configPath}:`,
       "",
       `[mcp_servers.${SERVER_NAME}]`,
       `command = "pyx-mem"`,
       `args = ${JSON.stringify(pyxMemArgs(remote))}`,
+      ...codexHome ? [`env = { CODEX_HOME = ${JSON.stringify(codexHome)} }`] : [],
       "",
       "Do NOT add your pyx-memory API key here. Run `pyx-mem login` to store it in the OS credential store.",
       ""
@@ -2841,35 +2932,48 @@ function printHermesManualInstructions(remote) {
   );
 }
 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"]
+  "claude-code": { envDir: "CLAUDE_CONFIG_DIR", dir: [".claude"], file: "CLAUDE.md" },
+  codex: { envDir: "CODEX_HOME", dir: [".codex"], file: "AGENTS.md" },
+  "gemini-cli": { dir: [".gemini"], file: "GEMINI.md" },
+  "oh-my-pi": { dir: [".omp", "agent"], file: "RULES.md" }
 };
+function rulesFilePath(target, opts) {
+  if (!Object.hasOwn(RULES_FILE_TARGETS, target)) return void 0;
+  const spec = RULES_FILE_TARGETS[target];
+  const env = opts._env ?? (opts._homeDir === void 0 ? process.env : {});
+  const configDir = spec.envDir ? env[spec.envDir] : void 0;
+  return configDir ? join2(configDir, spec.file) : join2(opts._homeDir ?? homedir2(), ...spec.dir, spec.file);
+}
 function installMemoryRules(opts) {
-  const segs = RULES_FILE_TARGETS[opts.target];
-  if (!segs) return;
+  const filePath = rulesFilePath(opts.target, opts);
+  if (!filePath) 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 ?? homedir2();
-  const result = writeMemoryRulesFile({
-    filePath: join2(home, ...segs),
-    section: PERSISTENT_MEMORY_SECTION
-  });
+  const result = writeMemoryRulesFile({ filePath, section: PERSISTENT_MEMORY_SECTION });
   process.stdout.write(result.message);
 }
+function installMemoryRulesOnly(target, opts = {}) {
+  if (target === void 0 || !rulesFilePath(target, opts)) {
+    process.stderr.write(
+      `Error: \`pyx-mem mcp rules\` needs a host with a known rules file: ${Object.keys(RULES_FILE_TARGETS).join(", ")}.
+`
+    );
+    return EXIT.USAGE;
+  }
+  installMemoryRules({ ...opts, target, noRules: false });
+  return EXIT.OK;
+}
 function reconcileMemoryRules(opts = {}) {
-  const home = opts._homeDir ?? homedir2();
-  for (const segs of Object.values(RULES_FILE_TARGETS)) {
-    const filePath = join2(home, ...segs);
+  const section = opts.section ?? PERSISTENT_MEMORY_SECTION;
+  for (const target of Object.keys(RULES_FILE_TARGETS)) {
+    const filePath = rulesFilePath(target, opts);
     try {
       if (!existsSync3(filePath)) continue;
-      if (!hasPyxMemoryRules(readFileSync3(filePath, "utf8"))) continue;
-      const result = writeMemoryRulesFile({ filePath, section: PERSISTENT_MEMORY_SECTION });
+      const result = writeMemoryRulesFile({ filePath, section, refreshOnly: true });
       if (result.action !== "unchanged") {
         process.stderr.write(
           `pyx-memory: refreshed the "## Persistent Memory" rules in ${filePath}
@@ -2880,6 +2984,31 @@ function reconcileMemoryRules(opts = {}) {
     }
   }
 }
+var MAX_SERVER_RULES_BYTES = 16 * 1024;
+async function syncMemoryRulesFromServer(client, opts = {}) {
+  try {
+    const { tools } = await client.listTools();
+    if (!tools.some((tool) => tool.name === "get_memory_rules")) {
+      reconcileMemoryRules(opts);
+      return;
+    }
+    const result = await client.callTool({ name: "get_memory_rules", arguments: {} });
+    const [first] = result.content ?? [];
+    const section = first?.type === "text" ? first.text : void 0;
+    if (result.isError || !section || !isRulesSection(section)) {
+      throw new Error('the server returned no valid "## Persistent Memory" section');
+    }
+    reconcileMemoryRules({ ...opts, section });
+  } catch (err) {
+    process.stderr.write(
+      `pyx-memory: left the installed memory rules unchanged \u2014 could not fetch current rules (${err instanceof Error ? err.message : String(err)}).
+`
+    );
+  }
+}
+function isRulesSection(text) {
+  return text.startsWith("## Persistent Memory\n") && Buffer.byteLength(text, "utf8") <= MAX_SERVER_RULES_BYTES && !text.includes("<!-- pyx-memory:") && !/^\s*(```|~~~)/m.test(text);
+}
 function validateScope(scope) {
   if (VALID_SCOPES.has(scope)) return true;
   process.stderr.write(`Error: invalid --scope \`${scope}\`. Expected: local | user | project.
@@ -2909,14 +3038,12 @@ function writeJsonAndReport(filePath, agentLabel, entry, opts = {}) {
 
 // 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]);
+    await runMcpProxyServer({
+      readCredentials,
+      onConnected: (client) => syncMemoryRulesFromServer(client)
+    });
     return EXIT.OK;
   } catch (err) {
     process.stderr.write(`Internal error: ${err instanceof Error ? err.message : String(err)}
@@ -3370,6 +3497,10 @@ Commands:
                                                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.
+  mcp rules <target>                           Write or refresh only the always-on rules for
+                                               claude-code, codex, gemini-cli, or oh-my-pi (no MCP
+                                               registration). Honors CLAUDE_CONFIG_DIR / CODEX_HOME;
+                                               'pyx-mem mcp' keeps them current from the server.
 
 Notes:
   - Credentials are stored only in the OS credential store (Keychain / libsecret / Credential Manager).
@@ -3473,6 +3604,13 @@ function runMcpCommand(parsed) {
       parsed.flags["no-rules"] === true
     );
   }
+  if (parsed.subcommand === "rules") {
+    if (Object.keys(parsed.flags).length > 0) {
+      process.stderr.write("Error: `pyx-mem mcp rules <host>` takes no flags.\n");
+      return EXIT.USAGE;
+    }
+    return installMemoryRulesOnly(parsed.positional[0]);
+  }
   process.stderr.write(
     `Error: unknown subcommand \`mcp ${parsed.subcommand}\`. Run \`pyx-mem --help\`.
 `

package/dist/dashboard.mjs

@@ -11,10 +11,10 @@ import {
   toGraphologyFormat,
   transformGraphData,
   unreachableHealth
-} from "./chunk-QWLTZIIK.mjs";
-import "./chunk-HVJZDJGH.mjs";
+} from "./chunk-7YHCNO3N.mjs";
+import "./chunk-SGL73IY5.mjs";
 import "./chunk-KZKGRND2.mjs";
-import "./chunk-BUKDWHTY.mjs";
+import "./chunk-C46EE5BH.mjs";
 export {
   DashboardClient,
   Poller,

package/dist/{data-plane-contract-webbeMs5.d.ts → data-plane-contract-C5VqxrpF.d.ts}

@@ -186,6 +186,11 @@ declare const DATA_PLANE_OPERATION_COVERAGE: {
         readonly reasonCode: "nonchargeable_operation";
         readonly reason: "status is nonchargeable and must bypass data-plane reservation";
     };
+    readonly 'mcp:get_memory_rules': {
+        readonly support: "not_execution_ready";
+        readonly reasonCode: "nonchargeable_operation";
+        readonly reason: "the rules text is nonchargeable and must bypass data-plane reservation";
+    };
     readonly 'mcp:get_user_profile': {
         readonly support: "sqlite_atomic_one_step";
     };

package/dist/data-plane-contract.d.ts

@@ -1 +1 @@
-export { C as CanonicalDataPlaneObject, a as CanonicalDataPlaneValue, b as CompileContext, c as CompileDataPlaneRequest, d as CompileDataPlaneResult, f as CompiledDataPlaneExecutionPlan, D as DATA_PLANE_CATALOG_VERSION, g as DATA_PLANE_COMPILER_LIMITS, h as DATA_PLANE_CONTRACT_VERSION, i as DATA_PLANE_HTTP_RESPONSE_FRAME, j as DATA_PLANE_MANIFEST_FRAME, k as DATA_PLANE_MANIFEST_VERSION, l as DATA_PLANE_OPERATION_COVERAGE, m as DATA_PLANE_SEARCH_EMBEDDING_CONTRACT, n as DATA_PLANE_STEP_INPUT_FRAME, o as DataPlaneCatalogOperation, q as DataPlaneUnsupportedReasonCode, S as SupportedDataPlaneCatalogOperation, r as canonicalDataPlaneJson, s as compileDataPlaneRequest, t as hashDataPlaneHttpResponseV1, u as hashDataPlaneManifestV1, v as hashDataPlaneStepInputV1 } from './data-plane-contract-webbeMs5.js';
+export { C as CanonicalDataPlaneObject, a as CanonicalDataPlaneValue, b as CompileContext, c as CompileDataPlaneRequest, d as CompileDataPlaneResult, f as CompiledDataPlaneExecutionPlan, D as DATA_PLANE_CATALOG_VERSION, g as DATA_PLANE_COMPILER_LIMITS, h as DATA_PLANE_CONTRACT_VERSION, i as DATA_PLANE_HTTP_RESPONSE_FRAME, j as DATA_PLANE_MANIFEST_FRAME, k as DATA_PLANE_MANIFEST_VERSION, l as DATA_PLANE_OPERATION_COVERAGE, m as DATA_PLANE_SEARCH_EMBEDDING_CONTRACT, n as DATA_PLANE_STEP_INPUT_FRAME, o as DataPlaneCatalogOperation, q as DataPlaneUnsupportedReasonCode, S as SupportedDataPlaneCatalogOperation, r as canonicalDataPlaneJson, s as compileDataPlaneRequest, t as hashDataPlaneHttpResponseV1, u as hashDataPlaneManifestV1, v as hashDataPlaneStepInputV1 } from './data-plane-contract-C5VqxrpF.js';

package/dist/data-plane-contract.mjs

@@ -13,7 +13,7 @@ import {
   hashDataPlaneHttpResponseV1,
   hashDataPlaneManifestV1,
   hashDataPlaneStepInputV1
-} from "./chunk-BUKDWHTY.mjs";
+} from "./chunk-C46EE5BH.mjs";
 export {
   DATA_PLANE_CATALOG_VERSION,
   DATA_PLANE_COMPILER_LIMITS,

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { StoreInput as StoreInput$1, MemoryEntry as MemoryEntry$1, MemorySearchParams as MemorySearchParams$1, MemorySearchResult as MemorySearchResult$1, MemoryType as MemoryType$1, PrincipalContext as PrincipalContext$1, SensitivityLevel as SensitivityLevel$1, MemoryStats as MemoryStats$1, MemoryInsights as MemoryInsights$1, LineageParams as LineageParams$1, LineageResult as LineageResult$1, ReinforceParams as ReinforceParams$1, ReinforceResult as ReinforceResult$1, WikiLintReport as WikiLintReport$1, GraphRepairResult as GraphRepairResult$1, ExtractedImageMeta as ExtractedImageMeta$1, IngestEntity as IngestEntity$1, IngestRelationship as IngestRelationship$1, EntityExtractionResult as EntityExtractionResult$1, Topology as Topology$1, IngestEvent as IngestEvent$1, GraphEnrichEvent as GraphEnrichEvent$1, GraphNode as GraphNode$1, GraphTraversalResult as GraphTraversalResult$1, CorrectionRecord as CorrectionRecord$1 } from '@pyx-memory/shared';
 export { documentContentSource, documentGraphSource, documentImageSource } from '@pyx-memory/shared';
-export { e as encodeListCursorToken, p as parseListCursorToken } from './data-plane-contract-webbeMs5.js';
+export { e as encodeListCursorToken, p as parseListCursorToken } from './data-plane-contract-C5VqxrpF.js';
 
 /** ISO 8601 timestamp string */
 type Timestamp = string;

package/dist/index.mjs

@@ -2,7 +2,7 @@ import {
   DisabledMemory,
   MemoryClient,
   MemoryServerError
-} from "./chunk-HVJZDJGH.mjs";
+} from "./chunk-SGL73IY5.mjs";
 import {
   DEFAULTS,
   MEMORY_PROJECT_LABEL_MAX_CHARS,
@@ -37,7 +37,7 @@ import {
   normalizeGraphLabel,
   normalizeNameKey,
   parseListCursorToken
-} from "./chunk-BUKDWHTY.mjs";
+} from "./chunk-C46EE5BH.mjs";
 
 // src/preset.ts
 var DEFAULT_MEMORY_URL = `http://localhost:${DEFAULTS.MEMORY_SERVER_PORT}`;

package/dist/react.mjs

@@ -11,10 +11,10 @@ import {
   toGraphologyFormat,
   transformGraphData,
   unreachableHealth
-} from "./chunk-QWLTZIIK.mjs";
-import "./chunk-HVJZDJGH.mjs";
+} from "./chunk-7YHCNO3N.mjs";
+import "./chunk-SGL73IY5.mjs";
 import "./chunk-KZKGRND2.mjs";
-import "./chunk-BUKDWHTY.mjs";
+import "./chunk-C46EE5BH.mjs";
 
 // ../dashboard/src/hooks/use-consolidation-log.ts
 import { useCallback as useCallback2, useMemo } from "react";

package/package.json

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