@pyxmate/memory 1.2.0 → 1.4.0

package/dist/cli/pyx-mem.mjs

@@ -1,21 +1,8 @@
 #!/usr/bin/env node
 import {
-  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,
-  buildDesignGuide,
-  buildGraphStructuringPrompt
-} from "../chunk-XHEVB23R.mjs";
-import {
-  normalizeGraphLabel,
-  normalizeNameKey
-} from "../chunk-X6AYWXW7.mjs";
+  PERSISTENT_MEMORY_SECTION,
+  buildDesignGuide
+} from "../chunk-ML6VKYAL.mjs";
 
 // src/cli/exit-codes.ts
 var EXIT = {
@@ -352,7 +339,7 @@ async function promptMasked(label) {
 `);
     return value;
   }
-  return new Promise((resolve4, reject) => {
+  return new Promise((resolve3, reject) => {
     const previousEncoding = stdin.readableEncoding;
     stdin.setEncoding("utf8");
     stdin.setRawMode(true);
@@ -370,7 +357,7 @@ async function promptMasked(label) {
         if (ch === "\n" || ch === "\r") {
           cleanup();
           stdout.write("\n");
-          resolve4(buf.trim());
+          resolve3(buf.trim());
           return;
         }
         if (ch === "") {
@@ -811,7 +798,7 @@ function createProxyServer(client, version, uploadLocalFile) {
   return server;
 }
 async function runMcpProxyServer(opts) {
-  const version = opts.version ?? (true ? "1.2.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();
@@ -828,14 +815,14 @@ async function runMcpProxyServer(opts) {
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     throw new Error(
-      `Could not reach the pyx-memory remote MCP at ${url.href}: ${msg}. Verify the endpoint and key with \`pyx-mem doctor\`, or run the legacy bundled server with \`pyx-mem mcp --bundled\`.`
+      `Could not reach the pyx-memory remote MCP at ${url.href}: ${msg}. Verify the endpoint and key with \`pyx-mem doctor\`.`
     );
   }
   try {
     const server = createProxyServer(client, version, createLocalFileUploader(read.credentials));
     const transport = new StdioServerTransport();
-    const closed = new Promise((resolve4) => {
-      transport.onclose = () => resolve4();
+    const closed = new Promise((resolve3) => {
+      transport.onclose = () => resolve3();
     });
     await server.connect(transport);
     await closed;
@@ -845,765 +832,15 @@ async function runMcpProxyServer(opts) {
   }
 }
 
-// src/mcp/server.ts
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport as StdioServerTransport2 } from "@modelcontextprotocol/sdk/server/stdio.js";
-
-// src/mcp/prompts/index.ts
-import { z } from "zod";
-var structureGraphPrompt = {
-  name: "structure_graph",
-  description: STRUCTURE_GRAPH_PROMPT_DESC,
-  register(server) {
-    server.registerPrompt(
-      "structure_graph",
-      {
-        title: "Structure content into a knowledge graph",
-        description: STRUCTURE_GRAPH_PROMPT_DESC,
-        argsSchema: {
-          content: z.string().min(1).describe("The memory content to extract graph fields from.")
-        }
-      },
-      ({ content }) => ({
-        messages: [
-          { role: "user", content: { type: "text", text: buildGraphStructuringPrompt(content) } }
-        ]
-      })
-    );
-  }
-};
-var ALL_PROMPTS = [structureGraphPrompt];
-
-// src/mcp/tools/corrections.ts
-import { z as z3 } from "zod";
-
-// src/mcp/tools/scopes.ts
-import { z as z2 } from "zod";
-var scopeShape = {
-  tenantId: z2.string().optional().describe("Sent as X-Tenant-Id for multi-tenant isolation."),
-  userId: z2.string().optional().describe("Sent as X-User-Id."),
-  teamId: z2.string().optional().describe("Sent as X-Team-Id."),
-  callerAccessLevel: z2.enum(["public", "internal", "secret"]).optional().describe("Sent as X-Caller-Access-Level for sensitivity filtering.")
-};
-
-// src/mcp/tools/corrections.ts
-var recordInputShape = {
-  namespaceId: z3.string().min(1).optional().describe("Namespace id to record into. Omit in single-tenant deployments (namespace-free)."),
-  whatWasWrong: z3.string().min(1).describe("What the agent did wrong."),
-  whatToDoInstead: z3.string().min(1).describe("The corrective instruction to follow instead."),
-  appliesWhen: z3.string().min(1).describe("When this correction applies \u2014 the task context future tasks are matched against."),
-  project: z3.string().optional().describe("Optional project scope; omit to apply to all projects."),
-  taskShape: z3.string().optional().describe("Optional task-shape hint stored for provenance."),
-  ...scopeShape
-};
-var recordCorrectionTool = {
-  name: "record_correction",
-  config: {
-    title: "Record a pyx-memory correction",
-    description: 'Record an explicit user correction so the same mistake can be avoided next time. Call this when the user explicitly corrects the agent ("you did X wrong; do Y instead"). HTTP proxy to POST /api/memory/corrections \u2014 returns `{id, createdAt}`.',
-    inputSchema: recordInputShape,
-    annotations: { readOnlyHint: false, openWorldHint: true }
-  },
-  handler: (deps) => async (raw) => {
-    const args = raw;
-    const creds = await deps.readCredentials();
-    if (!creds.ok) return creds.result;
-    const http = createHttpClient(creds.credentials, deps.fetchImpl);
-    const res = await http.requestJson({
-      method: "POST",
-      path: "/api/memory/corrections",
-      body: {
-        ...args.namespaceId !== void 0 ? { namespaceId: args.namespaceId } : {},
-        whatWasWrong: args.whatWasWrong,
-        whatToDoInstead: args.whatToDoInstead,
-        appliesWhen: args.appliesWhen,
-        ...args.project !== void 0 ? { project: args.project } : {},
-        ...args.taskShape !== void 0 ? { taskShape: args.taskShape } : {}
-      },
-      scope: args
-    });
-    return res.ok ? mcpJson(res.data) : res.result;
-  }
-};
-var fetchInputShape = {
-  namespaceId: z3.string().min(1).optional().describe("Namespace id whose corrections to fetch. Omit in single-tenant deployments."),
-  taskShape: z3.string().min(1).describe("Shape of the task about to run \u2014 scored against each correction."),
-  project: z3.string().optional().describe("Optional project filter."),
-  limit: z3.number().int().positive().optional().describe("Max corrections to return (cap 5)."),
-  ...scopeShape
-};
-var fetchApplicableCorrectionsTool = {
-  name: "fetch_applicable_corrections",
-  config: {
-    title: "Fetch applicable pyx-memory corrections",
-    description: "Fetch the corrections applicable to a task shape (\u22645, ranked by overlap then recency). pyx never auto-prepends \u2014 you decide whether to follow them. HTTP proxy to GET /api/memory/corrections \u2014 returns a `CorrectionRecord[]` (`[]` when none apply).",
-    inputSchema: fetchInputShape,
-    annotations: { readOnlyHint: true, openWorldHint: true }
-  },
-  handler: (deps) => async (raw) => {
-    const args = raw;
-    const creds = await deps.readCredentials();
-    if (!creds.ok) return creds.result;
-    const http = createHttpClient(creds.credentials, deps.fetchImpl);
-    const res = await http.requestJson({
-      method: "GET",
-      path: "/api/memory/corrections",
-      query: {
-        namespaceId: args.namespaceId,
-        taskShape: args.taskShape,
-        project: args.project,
-        limit: args.limit
-      },
-      scope: args
-    });
-    return res.ok ? mcpJson(res.data) : res.result;
-  }
-};
-
-// src/mcp/tools/delete.ts
-import { z as z4 } from "zod";
-var inputShape = {
-  id: z4.string().min(1).describe("Required memory entry id to delete."),
-  reason: z4.string().min(1).describe("Required reason for deletion (audit)."),
-  ...scopeShape
-};
-var deleteMemoryTool = {
-  name: "delete_memory",
-  config: {
-    title: "Delete pyx-memory entry",
-    description: "Delete one memory entry by id with an explicit reason. Self-hosted instances require an admin key; cloud delegates to tenant policy.",
-    inputSchema: inputShape,
-    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true }
-  },
-  handler: (deps) => async (raw) => {
-    const args = raw;
-    const creds = await deps.readCredentials();
-    if (!creds.ok) return creds.result;
-    const http = createHttpClient(creds.credentials, deps.fetchImpl);
-    const res = await http.requestJson({
-      method: "DELETE",
-      path: `/api/memory/entries/${encodeURIComponent(args.id)}`,
-      query: { reason: args.reason },
-      scope: args
-    });
-    return res.ok ? mcpJson({ deleted: args.id }) : res.result;
-  }
-};
-
-// src/mcp/tools/get.ts
-import { z as z5 } from "zod";
-var inputShape2 = {
-  id: z5.string().min(1).describe("Required memory entry id."),
-  ...scopeShape
-};
-var getMemoryTool = {
-  name: "get_memory",
-  config: {
-    title: "Get pyx-memory entry",
-    description: "Fetch one memory entry by id. Multi-tenant headers and X-Caller-Access-Level are honored for sensitivity redaction.",
-    inputSchema: inputShape2,
-    annotations: { readOnlyHint: true, openWorldHint: true }
-  },
-  handler: (deps) => async (raw) => {
-    const args = raw;
-    const creds = await deps.readCredentials();
-    if (!creds.ok) return creds.result;
-    const http = createHttpClient(creds.credentials, deps.fetchImpl);
-    const res = await http.requestJson({
-      method: "GET",
-      path: `/api/memory/entries/${encodeURIComponent(args.id)}`,
-      scope: args
-    });
-    return res.ok ? mcpJson(res.data) : res.result;
-  }
-};
-
-// src/mcp/tools/ingest.ts
-import { readFile as readFile2, stat as stat2 } from "fs/promises";
-import { basename as basename2, extname, isAbsolute as isAbsolute2, resolve as resolve2 } from "path";
-import { z as z6 } from "zod";
-var IMAGE_EXT = /* @__PURE__ */ new Set([".png", ".jpg", ".jpeg", ".webp", ".gif", ".bmp", ".tiff", ".svg"]);
-var MAX_BYTES = 50 * 1024 * 1024;
-var INGEST_ENDPOINT = "/api/memory/ingest/file";
-var inputShape3 = {
-  path: z6.string().min(1).describe(
-    "Local file path readable by the pyx-mem process. Uploaded as multipart `file`. Images require `description`; documents auto-extract text."
-  ),
-  description: z6.string().optional().describe(
-    "REQUIRED for images so the entry is semantically searchable. Optional for documents with extractable text."
-  ),
-  namespaceId: z6.string().optional().describe("Optional ReBAC namespace for entries created from this file."),
-  ...scopeShape
-};
-var ingestMemoryFileTool = {
-  name: "ingest_memory_file",
-  config: {
-    title: "Ingest file into pyx-memory",
-    description: "Upload a document or image into pyx-memory. Images REQUIRE description. Large docx/xlsx/pptx should be pre-extracted to txt/md. 50MB cap.",
-    inputSchema: inputShape3,
-    annotations: { readOnlyHint: false, idempotentHint: false, openWorldHint: true }
-  },
-  // `path` is a host-local file. On the remote `/mcp` route the server cannot
-  // read it, so this descriptor lets the local proxy bridge the upload (read
-  // bytes here, multipart-POST to the declared endpoint). The bundled handler
-  // below ignores it. Field names map 1:1 to the multipart form built below.
-  localUpload: {
-    pathArg: "path",
-    endpoint: INGEST_ENDPOINT,
-    fileField: "file",
-    optionalArgs: ["description", "namespaceId"],
-    maxBytes: MAX_BYTES
-  },
-  handler: (deps) => async (raw) => {
-    const args = raw;
-    const ext = extname(args.path).toLowerCase();
-    const isImage = IMAGE_EXT.has(ext);
-    if (isImage && !args.description?.trim()) {
-      return mcpText(
-        `Image ingest requires a non-empty \`description\`. Provide a 1-2 sentence summary of the image content so it becomes searchable.`,
-        true
-      );
-    }
-    const abs = isAbsolute2(args.path) ? args.path : resolve2(args.path);
-    let bytes;
-    try {
-      const info = await stat2(abs);
-      if (info.size > MAX_BYTES) {
-        return mcpText(`File too large: ${info.size} bytes > 50MB cap.`, true);
-      }
-      bytes = await readFile2(abs);
-    } catch (err) {
-      return mcpText(
-        `Failed to read ${abs}: ${err instanceof Error ? err.message : String(err)}.`,
-        true
-      );
-    }
-    const creds = await deps.readCredentials();
-    if (!creds.ok) return creds.result;
-    const http = createHttpClient(creds.credentials, deps.fetchImpl);
-    const res = await http.requestMultipart({
-      path: INGEST_ENDPOINT,
-      scope: args,
-      formData: () => {
-        const form = new FormData();
-        const file = new File([new Uint8Array(bytes)], basename2(abs));
-        form.set("file", file);
-        if (args.description) form.set("description", args.description);
-        if (args.namespaceId) form.set("namespaceId", args.namespaceId);
-        return form;
-      }
-    });
-    return res.ok ? mcpJson(res.data) : res.result;
-  }
-};
-
-// src/mcp/tools/lineage.ts
-import { z as z7 } from "zod";
-var inputShape4 = {
-  subject: z7.string().optional().describe("Graph subject to trace, used with relation for graph lineage."),
-  relation: z7.string().optional().describe("Graph relation to trace for the subject."),
-  entryId: z7.string().optional().describe("Memory entry id to trace through its supersededBy chain."),
-  asOf: z7.string().optional().describe("Only include lineage versions ingested by this ISO-8601 time."),
-  eventTimeStart: z7.string().optional().describe("Inclusive event-time start (ISO-8601)."),
-  eventTimeEnd: z7.string().optional().describe("Inclusive event-time end (ISO-8601)."),
-  beforeValue: z7.string().optional().describe("Stop before the lineage version with this value."),
-  limit: z7.number().int().positive().optional().describe("Maximum lineage versions to return."),
-  ...scopeShape
-};
-var lineageTool = {
-  name: "lineage",
-  config: {
-    title: "Trace pyx-memory fact lineage",
-    description: "Return the time-ordered history of how a fact evolved: subject+relation traces graph lineage, entryId traces a supersededBy chain. Use for questions like what did X use before Y or how did this fact evolve.",
-    inputSchema: inputShape4,
-    annotations: { readOnlyHint: true, openWorldHint: true }
-  },
-  handler: (deps) => async (raw) => {
-    const args = raw;
-    const creds = await deps.readCredentials();
-    if (!creds.ok) return creds.result;
-    const http = createHttpClient(creds.credentials, deps.fetchImpl);
-    const res = await http.requestJson({
-      method: "GET",
-      path: "/api/memory/lineage",
-      query: {
-        subject: args.subject,
-        relation: args.relation,
-        entryId: args.entryId,
-        asOf: args.asOf,
-        eventTimeStart: args.eventTimeStart,
-        eventTimeEnd: args.eventTimeEnd,
-        beforeValue: args.beforeValue,
-        limit: args.limit
-      },
-      scope: args
-    });
-    return res.ok ? mcpJson(res.data) : res.result;
-  }
-};
-
-// src/mcp/tools/list.ts
-import { z as z8 } from "zod";
-var inputShape5 = {
-  mode: z8.enum(["entries", "log"]).optional().describe(
-    "Listing mode. `entries` (default) returns paginated entries by filter; `log` returns the chronological memory log."
-  ),
-  page: z8.number().int().min(1).optional().describe("1-based page index for entries mode."),
-  limit: z8.number().int().min(1).max(200).optional().describe("Page size; server clamps."),
-  type: z8.enum(["short-term", "long-term", "working", "episodic", "summary"]).optional().describe("Filter by memory type."),
-  agentId: z8.string().optional().describe("Filter to memories from this agentId."),
-  since: z8.string().optional().describe("ISO-8601 lower bound for log mode."),
-  ...scopeShape
-};
-var listMemoriesTool = {
-  name: "list_memories",
-  config: {
-    title: "List pyx-memory",
-    description: "List recent memory entries or a chronological memory log. Same tool for both reads \u2014 `mode` controls which.",
-    inputSchema: inputShape5,
-    annotations: { readOnlyHint: true, openWorldHint: true }
-  },
-  handler: (deps) => async (raw) => {
-    const args = raw;
-    const creds = await deps.readCredentials();
-    if (!creds.ok) return creds.result;
-    const http = createHttpClient(creds.credentials, deps.fetchImpl);
-    const mode = args.mode ?? "entries";
-    const path = mode === "log" ? "/api/memory/log" : "/api/memory/entries";
-    const res = await http.requestJson({
-      method: "GET",
-      path,
-      query: {
-        page: args.page,
-        limit: args.limit,
-        type: args.type,
-        agentId: args.agentId,
-        since: args.since
-      },
-      scope: args
-    });
-    return res.ok ? mcpJson(res.data) : res.result;
-  }
-};
-
-// src/mcp/tools/profile.ts
-import { z as z9 } from "zod";
-var getInputShape = {
-  namespaceId: z9.string().min(1).describe("Namespace id whose user-profile to fetch."),
-  ...scopeShape
-};
-var getUserProfileTool = {
-  name: "get_user_profile",
-  config: {
-    title: "Get pyx-memory user profile",
-    description: "Fetch the current user-profile snapshot for a namespace. HTTP proxy to GET /api/memory/profile/user \u2014 returns `{content, updatedAt, contentSize}` or a not-found error.",
-    inputSchema: getInputShape,
-    annotations: { readOnlyHint: true, openWorldHint: true }
-  },
-  handler: (deps) => async (raw) => {
-    const args = raw;
-    const creds = await deps.readCredentials();
-    if (!creds.ok) return creds.result;
-    const http = createHttpClient(creds.credentials, deps.fetchImpl);
-    const res = await http.requestJson({
-      method: "GET",
-      path: "/api/memory/profile/user",
-      query: { namespaceId: args.namespaceId },
-      scope: args
-    });
-    return res.ok ? mcpJson(res.data) : res.result;
-  }
-};
-var upsertInputShape = {
-  namespaceId: z9.string().min(1).describe("Namespace id to upsert the user-profile into."),
-  content: z9.string().min(1).describe("Full freeform profile content (UTF-8, \u22648192 bytes; server enforces the cap)."),
-  ...scopeShape
-};
-var upsertUserProfileTool = {
-  name: "upsert_user_profile",
-  config: {
-    title: "Upsert pyx-memory user profile",
-    description: "Upsert the user-profile snapshot for a namespace. HTTP proxy to PUT /api/memory/profile/user \u2014 returns `{updatedAt, contentSize}`. Idempotent: re-upsert preserves `createdAt` and refreshes `updatedAt`.",
-    inputSchema: upsertInputShape,
-    annotations: { readOnlyHint: false, openWorldHint: true }
-  },
-  handler: (deps) => async (raw) => {
-    const args = raw;
-    const creds = await deps.readCredentials();
-    if (!creds.ok) return creds.result;
-    const http = createHttpClient(creds.credentials, deps.fetchImpl);
-    const res = await http.requestJson({
-      method: "PUT",
-      path: "/api/memory/profile/user",
-      body: { namespaceId: args.namespaceId, content: args.content },
-      scope: args
-    });
-    return res.ok ? mcpJson(res.data) : res.result;
-  }
-};
-
-// src/mcp/tools/reinforce.ts
-import { z as z10 } from "zod";
-var inputShape6 = {
-  entryIds: z10.array(z10.string().min(1)).min(1).describe("Memory entry ids that were actually used."),
-  signal: z10.enum(["context_included", "cited", "explicit_positive"]).describe("Reinforcement signal: context_included < cited < explicit_positive."),
-  at: z10.union([z10.string(), z10.number()]).optional().describe("Recall time as epoch-ms or full ISO-8601 timestamp with timezone."),
-  ...scopeShape
-};
-var reinforceTool = {
-  name: "reinforce",
-  config: {
-    title: "Reinforce used pyx-memory entries",
-    description: "Reinforce memories the agent actually USED (recall reinforces \u2014 raises strength so they surface in quick/medium effort tiers). signal: context_included < cited < explicit_positive.",
-    inputSchema: inputShape6,
-    annotations: { readOnlyHint: false, openWorldHint: true }
-  },
-  handler: (deps) => async (raw) => {
-    const args = raw;
-    const creds = await deps.readCredentials();
-    if (!creds.ok) return creds.result;
-    const http = createHttpClient(creds.credentials, deps.fetchImpl);
-    const res = await http.requestJson({
-      method: "POST",
-      path: "/api/memory/reinforce",
-      body: { entryIds: args.entryIds, signal: args.signal, at: args.at },
-      scope: args
-    });
-    return res.ok ? mcpJson(res.data) : res.result;
-  }
-};
-
-// src/mcp/tools/search.ts
-import { z as z11 } from "zod";
-var inputShape7 = {
-  query: z11.string().min(1).describe("Required natural-language search text."),
-  limit: z11.number().int().min(1).max(100).optional().describe(SEARCH_LIMIT_DESC),
-  strategy: z11.enum(["naive", "graph", "hybrid"]).optional().describe(
-    "RAG strategy. Defaults to `hybrid` (cross-encoder reranking, multi-entity decomposition, confidence scoring) and is sent explicitly when omitted; pass `naive` for a lighter vector-only search or `graph` for graph-augmented retrieval."
-  ),
-  effort: z11.enum(["quick", "medium", "deep"]).optional().describe(
-    "Retrieval depth: quick=strongest, medium=default-depth, deep=everything including archived/superseded."
-  ),
-  type: z11.enum(["short-term", "long-term", "working", "episodic", "summary"]).optional().describe("Filter by memory type."),
-  agentId: z11.string().optional().describe("Filter to memories stored for this agentId."),
-  abstentionThreshold: z11.number().min(0).max(1).optional().describe("Enable confidence scoring; abstain when confidence falls below this value (0\u20131)."),
-  eventTimeStart: z11.string().optional().describe("Inclusive event-time start (ISO-8601); must be paired with eventTimeEnd."),
-  eventTimeEnd: z11.string().optional().describe("Inclusive event-time end (ISO-8601); must be paired with eventTimeStart."),
-  asOf: z11.string().optional().describe("Only include memories ingested before this ISO-8601 timestamp."),
-  anchorTime: z11.string().optional().describe(
-    'Soft recency ANCHOR (ISO-8601) \u2014 ranks results by proximity to this time instead of now; never excludes anything. When the question names a relative time ("two months ago", "last year", "3\uB144 \uC804"), resolve it against the current date yourself and pass the absolute timestamp here; prefer this over eventTimeStart/End unless a strict window is required, because hard filters drop last-known-before facts.'
-  ),
-  enumerationConcept: z11.string().trim().min(1).optional().describe(SEARCH_ENUMERATION_CONCEPT_DESC),
-  enableRerank: z11.boolean().optional().describe(
-    "Opt into multilingual cross-encoder reranking (hybrid strategy only). Sharply improves Korean/cross-lingual ordering at higher latency; leave off for the fast default path."
-  ),
-  ...scopeShape
-};
-var searchMemoriesTool = {
-  name: "search_memories",
-  config: {
-    title: "Search pyx-memory",
-    description: "Search durable pyx-memory entries with hybrid/vector/keyword/graph strategy, tenant scope, sensitivity access, and optional confidence/abstention.",
-    inputSchema: inputShape7,
-    annotations: { readOnlyHint: true, openWorldHint: true }
-  },
-  handler: (deps) => async (raw) => {
-    const args = raw;
-    const creds = await deps.readCredentials();
-    if (!creds.ok) return creds.result;
-    const http = createHttpClient(creds.credentials, deps.fetchImpl);
-    const res = await http.requestJson({
-      method: "GET",
-      path: "/api/memory/search",
-      query: {
-        query: args.query,
-        limit: args.limit,
-        // Force `hybrid` unless the caller explicitly overrides. The server's
-        // own default is hybrid too, but older tenant instances default to
-        // `naive` (1–2 results vs hybrid's 15–20) — sending it explicitly makes
-        // recall deterministic regardless of the instance version.
-        strategy: args.strategy ?? "hybrid",
-        effort: args.effort,
-        type: args.type,
-        agentId: args.agentId,
-        abstentionThreshold: args.abstentionThreshold,
-        eventTimeStart: args.eventTimeStart,
-        eventTimeEnd: args.eventTimeEnd,
-        asOf: args.asOf,
-        anchorTime: args.anchorTime,
-        enumerationConcept: args.enumerationConcept,
-        enableRerank: args.enableRerank ? "true" : void 0
-      },
-      scope: args
-    });
-    return res.ok ? mcpJson(res.data) : res.result;
-  }
-};
-
-// src/mcp/tools/status.ts
-var inputShape8 = {};
-var statusTool = {
-  name: "status",
-  config: {
-    title: "Get pyx-memory topology",
-    description: "Fetch the running pyx-memory server topology from GET /status when available. Hosted gateways that expose /health but not /status return an explicit topologyUnavailable result with the health payload.",
-    inputSchema: inputShape8,
-    annotations: { readOnlyHint: true, openWorldHint: true }
-  },
-  handler: (deps) => async () => {
-    const creds = await deps.readCredentials();
-    if (!creds.ok) return creds.result;
-    const http = createHttpClient(creds.credentials, deps.fetchImpl);
-    const res = await http.requestJson({ method: "GET", path: "/status" });
-    if (res.ok) return mcpJson(res.data);
-    if (res.status !== 404) return res.result;
-    const health = await http.requestJson({ method: "GET", path: "/health" });
-    if (!health.ok) return res.result;
-    return mcpJson({
-      topologyUnavailable: true,
-      reason: "GET /status returned 404; this endpoint exposes /health but not topology status.",
-      statusEndpoint: "/status",
-      healthEndpoint: "/health",
-      health: health.data
-    });
-  }
-};
-
-// src/mcp/tools/store.ts
-import { z as z12 } from "zod";
-var entityTypes = ["PERSON", "ORGANIZATION", "CONCEPT", "TOOL", "LOCATION", "EVENT"];
-var preferredRelationshipTypes = [
-  "USES",
-  "OWNS",
-  "DEPENDS_ON",
-  "RELATED_TO",
-  "CREATED_BY",
-  "PART_OF",
-  "IS_A",
-  "WORKS_AT",
-  "LOCATED_IN"
-];
-var RELATIONSHIP_TYPE_DESC = `Relationship type \u2014 freeform label; preferred: ${preferredRelationshipTypes.join(", ")}.`;
-var storeTargets = ["sqlite", "vector", "graph"];
-var entityShape = z12.object({
-  name: z12.string().min(1).describe("Entity name as referenced in content."),
-  type: z12.enum(entityTypes).describe("Entity type.")
-});
-var inputShape9 = {
-  content: z12.string().min(1).describe("Concise factual statement to persist; decision, not deliberation."),
-  topic: z12.string().min(1).describe("Required metadata.topic for retrieval grouping."),
-  project: z12.string().min(1).describe("Required metadata.project namespace."),
-  type: z12.enum(["short-term", "long-term", "working", "episodic", "summary"]).optional().describe("Memory type. Default long-term."),
-  targets: z12.array(z12.enum(storeTargets)).optional().describe(
-    "Storage targets. Include 'graph' when you provide entities/relationships or want zero graph write counts reported."
-  ),
-  importance: z12.number().int().min(1).max(10).optional().describe("Importance 1\u201310."),
-  eventTime: z12.string().optional().describe(STORE_EVENT_TIME_DESC),
-  source: z12.string().optional().describe("Free-form origin (filename, URL, conversation id)."),
-  agentId: z12.string().optional().describe("Agent identifier stored alongside the entry."),
-  sessionId: z12.string().optional().describe("Session identifier for grouping."),
-  parentId: z12.string().optional().describe("Parent memory entry id (hierarchical)."),
-  entities: z12.array(entityShape).optional().describe(STORE_ENTITIES_DESC),
-  relationships: z12.array(
-    z12.object({
-      source: z12.string().min(1).describe("Source entity name (must appear in entities array)."),
-      target: z12.string().min(1).describe("Target entity name (must appear in entities array)."),
-      type: z12.string().min(1).describe(RELATIONSHIP_TYPE_DESC)
-    })
-  ).optional().describe(STORE_RELATIONSHIPS_DESC),
-  triples: z12.array(
-    z12.object({
-      subject: entityShape.describe("Subject entity (source node)."),
-      relation: z12.string().min(1).describe(RELATIONSHIP_TYPE_DESC),
-      object: entityShape.describe("Object entity (target node).")
-    })
-  ).optional().describe(STORE_TRIPLES_DESC),
-  extractEntities: z12.boolean().optional().describe(
-    "Override extraction: false skips extraction; true asks the server-side extraction brain to run and errors loudly when none is configured."
-  ),
-  entitiesOnly: z12.boolean().optional().describe(
-    "Set true to deliberately store entities with no relationships (e.g. a single concept). Otherwise a graph store with 2+ entities and 0 relationships is refused so isolated nodes do not accumulate."
-  ),
-  ...scopeShape
-};
-function materializeGraphInput(args) {
-  const entities = /* @__PURE__ */ new Map();
-  const addEntity = (e) => {
-    const key = `${normalizeNameKey(e.name)}|${e.type}`;
-    if (!entities.has(key)) entities.set(key, e);
-  };
-  const relationships = /* @__PURE__ */ new Map();
-  const addRel = (rel) => {
-    const key = `${normalizeNameKey(rel.source)}|${normalizeNameKey(rel.target)}|${normalizeGraphLabel(rel.type, "RELATED_TO")}`;
-    if (!relationships.has(key)) relationships.set(key, rel);
-  };
-  for (const e of args.entities ?? []) addEntity(e);
-  for (const r of args.relationships ?? []) addRel(r);
-  for (const t of args.triples ?? []) {
-    addEntity(t.subject);
-    addEntity(t.object);
-    addRel({ source: t.subject.name, target: t.object.name, type: t.relation });
-  }
-  return { entities: [...entities.values()], relationships: [...relationships.values()] };
-}
-var storeMemoryTool = {
-  name: "store_memory",
-  config: {
-    title: "Store pyx-memory entry",
-    description: STORE_TOOL_DESC,
-    inputSchema: inputShape9,
-    annotations: { readOnlyHint: false, idempotentHint: false, openWorldHint: true }
-  },
-  handler: (deps) => async (raw) => {
-    const args = raw;
-    const { entities, relationships } = materializeGraphInput(args);
-    const graphTargeted = !args.targets || args.targets.includes("graph");
-    const entityNameKeys = new Set(entities.map((e) => normalizeNameKey(e.name)));
-    const resolvableRelationships = relationships.filter((r) => {
-      const source = normalizeNameKey(r.source);
-      const target = normalizeNameKey(r.target);
-      return source !== target && entityNameKeys.has(source) && entityNameKeys.has(target);
-    }).length;
-    if (graphTargeted && entities.length >= 2 && resolvableRelationships === 0 && !args.entitiesOnly && args.extractEntities !== true) {
-      return mcpText(
-        `GRAPH_RELATIONSHIPS_REQUIRED: this store_memory call declares ${entities.length} entities but no relationship that connects them. Isolated nodes will not connect into the knowledge graph. Re-call store_memory with a \`relationships\` array (or \`triples\`) linking the entities (each { source, target, type }; source/target must be entity names from this call), OR set \`entitiesOnly: true\` if these entities are intentionally unconnected. Do not retry unchanged. If your MCP host exposes prompts, the \`structure_graph\` prompt produces the relationship/triple fields to add.`,
-        true
-      );
-    }
-    const creds = await deps.readCredentials();
-    if (!creds.ok) return creds.result;
-    const http = createHttpClient(creds.credentials, deps.fetchImpl);
-    const body = {
-      content: args.content,
-      type: args.type ?? "long-term",
-      targets: args.targets,
-      metadata: {
-        source: "agent",
-        topic: args.topic,
-        project: args.project
-      },
-      importance: args.importance,
-      eventTime: args.eventTime,
-      agentId: args.agentId,
-      sessionId: args.sessionId,
-      parentId: args.parentId,
-      entities: entities.length > 0 ? entities : void 0,
-      relationships: relationships.length > 0 ? relationships : void 0,
-      ...args.extractEntities !== void 0 ? { extractEntities: args.extractEntities } : {}
-    };
-    const res = await http.requestJson({
-      method: "POST",
-      path: "/api/memory/ingest",
-      body,
-      scope: args
-    });
-    return res.ok ? mcpJson(res.data) : res.result;
-  }
-};
-
-// src/mcp/tools/summarize.ts
-import { z as z13 } from "zod";
-var inputShape10 = {
-  entityName: z13.string().min(1).describe(
-    "Entity name to synthesize a profile for (PERSON, ORG, CONCEPT, TOOL, LOCATION, EVENT)."
-  ),
-  entityType: z13.enum(["PERSON", "ORGANIZATION", "CONCEPT", "TOOL", "LOCATION", "EVENT"]).optional().describe("Optional explicit entity type when the same name spans multiple categories."),
-  refresh: z13.boolean().optional().describe(
-    "Default false: fetch the existing synthesis. true: rebuild the synthesis from current memory (POST)."
-  ),
-  ...scopeShape
-};
-var summarizeMemoryEntityTool = {
-  name: "summarize_memory_entity",
-  config: {
-    title: "Synthesize pyx-memory entity",
-    description: "Fetch or refresh a reusable synthesis/profile for an entity (person, customer, project, tool, organization). Default fetches existing; set refresh:true to rebuild.",
-    inputSchema: inputShape10,
-    annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: true }
-  },
-  handler: (deps) => async (raw) => {
-    const args = raw;
-    const creds = await deps.readCredentials();
-    if (!creds.ok) return creds.result;
-    const http = createHttpClient(creds.credentials, deps.fetchImpl);
-    if (args.refresh) {
-      const res2 = await http.requestJson({
-        method: "POST",
-        path: "/api/memory/synthesis/entity",
-        body: { name: args.entityName, entityType: args.entityType },
-        scope: args
-      });
-      return res2.ok ? mcpJson(res2.data) : res2.result;
-    }
-    const res = await http.requestJson({
-      method: "GET",
-      path: "/api/memory/synthesis/entity",
-      query: { name: args.entityName, entityType: args.entityType },
-      scope: args
-    });
-    return res.ok ? mcpJson(res.data) : res.result;
-  }
-};
-
-// src/mcp/tools/index.ts
-var ALL_TOOLS = [
-  searchMemoriesTool,
-  storeMemoryTool,
-  getMemoryTool,
-  lineageTool,
-  reinforceTool,
-  listMemoriesTool,
-  deleteMemoryTool,
-  ingestMemoryFileTool,
-  summarizeMemoryEntityTool,
-  statusTool,
-  getUserProfileTool,
-  upsertUserProfileTool,
-  recordCorrectionTool,
-  fetchApplicableCorrectionsTool
-];
-var ALL_TOOL_NAMES = ALL_TOOLS.map((t) => t.name);
-
-// src/mcp/server.ts
-async function runMcpServer(opts) {
-  const fetchImpl = opts.fetchImpl ?? fetch;
-  const version = opts.version ?? (true ? "1.2.0" : "0.0.0-dev");
-  const server = new McpServer(
-    { name: "pyx-memory", version },
-    { instructions: PYX_MEMORY_INSTRUCTIONS, capabilities: { tools: {}, prompts: {} } }
-  );
-  for (const tool of ALL_TOOLS) {
-    const handle = tool.handler({
-      readCredentials: opts.readCredentials,
-      fetchImpl
-    });
-    server.registerTool(
-      tool.name,
-      tool.config,
-      async (args, extra) => handle(args, { signal: extra?.signal })
-    );
-  }
-  for (const prompt of ALL_PROMPTS) {
-    prompt.register(server);
-  }
-  const transport = new StdioServerTransport2();
-  const closed = new Promise((resolve4) => {
-    transport.onclose = () => resolve4();
-  });
-  await server.connect(transport);
-  await closed;
-}
-
 // src/cli/commands/mcp.ts
-async function mcpCommand(opts = {}) {
+async function mcpCommand() {
   const readCredentials = createReadCredentials(() => getDefaultKeychain());
-  const onStdinEnd = new Promise((resolve4) => {
-    process.stdin.once("end", resolve4);
-    process.stdin.once("close", resolve4);
+  const onStdinEnd = new Promise((resolve3) => {
+    process.stdin.once("end", resolve3);
+    process.stdin.once("close", resolve3);
   });
   try {
-    const run = opts.bundled ? runMcpServer({ readCredentials }) : runMcpProxyServer({ readCredentials });
-    await Promise.race([run, onStdinEnd]);
+    await Promise.race([runMcpProxyServer({ readCredentials }), onStdinEnd]);
     return EXIT.OK;
   } catch (err) {
     process.stderr.write(`Internal error: ${err instanceof Error ? err.message : String(err)}
@@ -1612,12 +849,13 @@ async function mcpCommand(opts = {}) {
   }
 }
 function resolveMcpMode(flags) {
-  const remote = flags.remote === true;
-  const bundled = flags.bundled === true;
-  if (remote && bundled) {
-    return { ok: false, error: "`--remote` and `--bundled` are mutually exclusive." };
+  if (flags.bundled === true) {
+    return {
+      ok: false,
+      error: "The bundled stdio MCP server was removed in v1.3.0. `pyx-mem mcp` now uses the hosted zero-touch path (server-owned tools + instructions; your key stays in the OS keychain). Drop `--bundled`. For a self-hosted server, point at it with `pyx-mem login --endpoint <url>` first."
+    };
   }
-  return { ok: true, bundled, implicit: !remote && !bundled };
+  return { ok: true };
 }
 
 // src/cli/commands/mcp-install.ts
@@ -1740,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";
@@ -2046,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.
@@ -2074,8 +1477,8 @@ 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 { basename as basename3, join as join2, resolve as resolve3 } from "path";
+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:
   pyx-memory:
@@ -2198,8 +1601,8 @@ function resolveTarget(args) {
     process.stderr.write("Error: --name requires a non-empty directory name.\n");
     return null;
   }
-  const targetDir = trimmedName ? resolve3(cwd, trimmedName) : cwd;
-  const appName = trimmedName || basename3(resolve3(cwd));
+  const targetDir = trimmedName ? resolve2(cwd, trimmedName) : cwd;
+  const appName = trimmedName || basename2(resolve2(cwd));
   return { targetDir, appName };
 }
 function buildFiles(targetDir, appName) {
@@ -2216,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 = basename3(file.path);
-    if (existsSync2(file.path)) {
+    const relativePath = basename2(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(
@@ -2305,21 +1708,27 @@ Commands:
   logout                                       Delete stored pyx-memory credentials.
   doctor [--json]                              Diagnose keychain, credentials, backend, MCP startup.
   scaffold [--name <dir>]                      Generate Docker, env, SDK, and memory design-guide starter files.
-  mcp [--bundled]                              Start the stdio MCP server. Default connects to the
-                                               hosted server so tools + instructions stay
-                                               server-owned (zero-touch updates; key stays in the
-                                               keychain). --bundled runs the legacy in-package server
-                                               (offline / version-pinned / host-local file ingest).
-  mcp install <target> [--scope user|local|project] [--remote]
-                                               Install pyx-memory MCP config for your AI agent.
-                                               --remote installs the hosted thin-proxy (zero-touch
-                                               updates; key stays in the keychain) instead of the
-                                               bundled stdio server.
+  mcp                                          Start the stdio MCP proxy to the hosted server, so
+                                               tools + instructions stay server-owned (zero-touch
+                                               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] [--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:
   - Credentials are stored only in the OS credential store (Keychain / libsecret / Credential Manager).
   - No plaintext token file is ever written.
+  - \`mcp --bundled\` was removed in v1.3.0 and now errors \u2014 drop the flag (the hosted path is the only transport).
   - Run \`pyx-mem doctor\` if something looks wrong.
 `;
 
@@ -2382,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(", ")}.
@@ -2391,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) {
@@ -2404,17 +1815,17 @@ function runMcpCommand(parsed) {
 `);
       return EXIT.USAGE;
     }
-    if (resolved.implicit) {
-      process.stderr.write(
-        "pyx-memory: `pyx-mem mcp` now connects to the hosted server (zero-touch \u2014 tools and instructions stay server-owned). Pass `--bundled` for the legacy in-package server.\n"
-      );
-    }
-    return mcpCommand({ bundled: resolved.bundled });
+    return mcpCommand();
   }
   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\`.