@pyxmate/memory 1.22.3 → 1.23.0

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.0" : "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(() => {
@@ -2591,17 +2593,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 +2622,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 +2853,49 @@ 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 });
       if (result.action !== "unchanged") {
         process.stderr.write(
           `pyx-memory: refreshed the "## Persistent Memory" rules in ${filePath}
@@ -2880,6 +2906,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 +2960,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 +3419,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 +3526,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.0",
   "type": "module",
   "description": "SDK for pyx-memory — Memory as a Service for AI agents",
   "license": "MIT",