@hasna/mementos 0.14.27 → 0.14.29

package/README.md

@@ -20,7 +20,8 @@ mementos setup agents
 
 `mementos setup agents` registers the hosted `mementos-mcp` server in Claude
 Code, Codex, OpenCode, and Antigravity config files. It also writes managed
-diagnostic snippets under `~/.config/mementos/agent-integrations`.
+diagnostic snippets and host-specific memory instructions under
+`~/.config/mementos/agent-integrations`.
 
 ## MCP
 
@@ -42,4 +43,7 @@ Claude Code also receives `UserPromptSubmit`, `SessionStart`, and `Stop` hook
 entries that call `mementos hook ...` and return hosted memory as hook context.
 Codex does not expose a native hook file in `~/.codex/config.toml`, so the
 installer registers MCP there and keeps the injection command in the managed
-integration snippets.
+integration snippets. OpenCode and Antigravity receive the same MCP registration
+plus host instruction files that tell the agent to use `memory.search`,
+`memory.save`, and `mementos inject` as the hosted fallback path when native
+hooks are unavailable.

package/dist/agent-setup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-setup.d.ts","sourceRoot":"","sources":["../src/agent-setup.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,qBAAqB,8DAA+D,CAAC;AAElG,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAExE,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,WAAW,CAAC;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,kBAAkB,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,kBAAkB,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;CAChF;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,WAAW,EAAE,oBAAoB,EAAE,CAAC;IACpC,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,oBAAoB,EAAE,CAAC;IACpC,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,YAAY,EAAE;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,QAAQ,GAAG,SAAS,CAAC;KAC9B,CAAC;IACF,EAAE,EAAE,OAAO,CAAC;IACZ,UAAU,EAAE,IAAI,CAAC;IACjB,eAAe,EAAE,OAAO,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,2BAA4B,SAAQ,iBAAiB;IACpE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CAC1C;AAED,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,iBAAsB,GAAG,cAAc,CA0CnF;AAED,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,2BAAgC,GAAG,oBAAoB,CAyBlG;AAED,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,iBAAsB,GAAG,cAAc,CAqCjF;AAED,wBAAgB,wBAAwB,CAAC,MAAM,SAAwB;;;EAStE;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAW9D"}
+{"version":3,"file":"agent-setup.d.ts","sourceRoot":"","sources":["../src/agent-setup.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,qBAAqB,8DAA+D,CAAC;AAElG,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAExE,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,WAAW,CAAC;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,kBAAkB,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,kBAAkB,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;CAChF;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,WAAW,EAAE,oBAAoB,EAAE,CAAC;IACpC,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,oBAAoB,EAAE,CAAC;IACpC,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,YAAY,EAAE;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,QAAQ,GAAG,SAAS,CAAC;KAC9B,CAAC;IACF,EAAE,EAAE,OAAO,CAAC;IACZ,UAAU,EAAE,IAAI,CAAC;IACjB,eAAe,EAAE,OAAO,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,2BAA4B,SAAQ,iBAAiB;IACpE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CAC1C;AAED,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,iBAAsB,GAAG,cAAc,CAkDnF;AAED,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,2BAAgC,GAAG,oBAAoB,CAyBlG;AAED,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,iBAAsB,GAAG,cAAc,CAqCjF;AAED,wBAAgB,wBAAwB,CAAC,MAAM,SAAwB;;;EAStE;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAW9D"}

package/dist/cli.js

@@ -15,6 +15,10 @@ function buildAgentSetupPlan(options = {}) {
   const hookCommand = "mementos hook stop";
   const injectCommand = "mementos inject";
   const files = [
+    {
+      path: join(baseDir, "mementos-instructions.md"),
+      content: renderSharedInstructions({ apiUrl, injectCommand, mcpCommand })
+    },
     {
       path: join(baseDir, "mementos-injection.md"),
       content: renderInjectionInstructions({ apiUrl, injectCommand })
@@ -31,6 +35,10 @@ function buildAgentSetupPlan(options = {}) {
     }
   ];
   for (const host of hosts) {
+    files.push({
+      path: join(baseDir, `${host}-instructions.md`),
+      content: renderHostInstructions(host, { apiUrl, injectCommand, mcpCommand })
+    });
     files.push({
       path: join(baseDir, `${host}.json`),
       content: `${JSON.stringify(renderHostConfig(host, { apiUrl, hookCommand, injectCommand, mcpCommand }), null, 2)}
@@ -155,11 +163,13 @@ function renderHostConfig(host, commands) {
     host,
     install: "bun install -g @hasna/mementos",
     remoteOnly: true,
+    nativeHooks: hasNativeHooks(host),
     mcp: renderMcpServerConfig(commands).mcpServers.mementos,
     hooks: {
       stop: commands.hookCommand,
       injection: commands.injectCommand
-    }
+    },
+    instructions: `${host}-instructions.md`
   };
 }
 function renderManagedHostConfig(host, commands) {
@@ -173,8 +183,15 @@ function renderManagedHostConfig(host, commands) {
       inject: commands.injectCommand,
       stopHook: commands.hookCommand
     },
+    injection: {
+      nativeHooks: hasNativeHooks(host),
+      fallbackCommand: commands.injectCommand,
+      mcpTools: ["memory.search", "memory.save", "memory.get", "memory.update", "memory.delete", "memory.usage"]
+    },
     files: {
       integrationDir: commands.baseDir,
+      sharedInstructions: join(commands.baseDir, "mementos-instructions.md"),
+      hostInstructions: join(commands.baseDir, `${host}-instructions.md`),
       injectionInstructions: join(commands.baseDir, "mementos-injection.md"),
       stopHook: join(commands.baseDir, "mementos-stop-hook.sh")
     }
@@ -455,6 +472,63 @@ MEMENTOS_API_URL=${apiUrl} MEMENTOS_API_TOKEN=$MEMENTOS_API_TOKEN ${injectComman
 This command reads hosted memory through the mementos.md API and prints a prompt-ready block.
 `;
 }
+function renderSharedInstructions({
+  apiUrl,
+  injectCommand,
+  mcpCommand
+}) {
+  return `# mementos.md Agent Instructions
+
+Use mementos.md as hosted durable memory for this agent host.
+
+- The MCP server command is \`${mcpCommand}\`.
+- The hosted API is \`${apiUrl}\`.
+- Use \`memory.search\` before non-trivial project work.
+- Use \`memory.save\` for durable decisions, root causes, and reusable context.
+- If the host does not provide a native hook, run \`${injectCommand} "<current task or question>"\` and include the returned hosted context in the next prompt.
+- Do not create or depend on a local memory database for the SaaS package.
+`;
+}
+function renderHostInstructions(host, commands) {
+  const common = renderSharedInstructions(commands);
+  if (host === "claude-code") {
+    return `${common}
+## Claude Code
+
+Claude Code has native mementos hooks installed by \`mementos setup agents\`.
+Use the mementos MCP server for explicit memory operations and let the
+\`UserPromptSubmit\`, \`SessionStart\`, and \`Stop\` hooks inject hosted context.
+`;
+  }
+  if (host === "codex") {
+    return `${common}
+## Codex
+
+Codex does not have a mementos native hook in its config file. Use the
+mementos MCP server for durable memory and run \`${commands.injectCommand}\`
+when you need prompt-ready hosted context before a turn.
+`;
+  }
+  if (host === "opencode") {
+    return `${common}
+## OpenCode
+
+Use the mementos MCP server for durable memory. When OpenCode cannot invoke a
+native lifecycle hook, run \`${commands.injectCommand}\` with the active task
+or error text and paste the hosted context into the next prompt.
+`;
+  }
+  return `${common}
+## Antigravity
+
+Use the mementos MCP server for durable memory. When Antigravity cannot invoke
+a native lifecycle hook, run \`${commands.injectCommand}\` with the active task
+or error text and include the hosted context before continuing.
+`;
+}
+function hasNativeHooks(host) {
+  return host === "claude-code";
+}
 function renderHookScript(command) {
   return `#!/usr/bin/env bash
 set -euo pipefail
@@ -807,14 +881,16 @@ async function runHook(args) {
     "user-prompt-submit": "UserPromptSubmit"
   };
   if (subcommand in hookEvents) {
-    const query2 = await readHookQuery();
+    const hookInput = await readHookInput();
+    const query2 = hookInput.query;
     const payload = await client.injectionContext({ query: query2, limit: 12 });
     const block = readTextPayload(payload) ?? formatMemoryInjection(payload);
+    const inboxBlock = await readInboxHookContext(hookInput);
     return {
       suppressOutput: true,
       hookSpecificOutput: {
         hookEventName: hookEvents[subcommand],
-        additionalContext: block
+        additionalContext: combineContextBlocks(inboxBlock, block)
       }
     };
   }
@@ -824,22 +900,97 @@ async function runHook(args) {
   const query = process.env.MEMENTOS_INJECTION_QUERY ?? process.cwd();
   return injectMemory([query]);
 }
-async function readHookQuery() {
-  if (process.env.MEMENTOS_INJECTION_QUERY)
-    return process.env.MEMENTOS_INJECTION_QUERY;
+async function readHookInput() {
+  if (process.env.MEMENTOS_INJECTION_QUERY) {
+    return {
+      agentName: process.env.MEMENTOS_AGENT_NAME,
+      query: process.env.MEMENTOS_INJECTION_QUERY
+    };
+  }
   const stdin = await readOptionalStdin();
-  if (!stdin)
-    return process.cwd();
+  if (!stdin) {
+    return {
+      agentName: process.env.MEMENTOS_AGENT_NAME,
+      query: process.cwd()
+    };
+  }
   try {
     const parsed = JSON.parse(stdin);
     const prompt = parsed.prompt ?? parsed.userPrompt ?? parsed.message ?? parsed.cwd;
-    if (typeof prompt === "string" && prompt.trim())
-      return prompt.trim();
+    return {
+      agentName: readHookText(parsed.agentName ?? parsed.agent ?? parsed.name) ?? process.env.MEMENTOS_AGENT_NAME,
+      projectKey: readHookText(parsed.projectKey ?? parsed.project),
+      query: typeof prompt === "string" && prompt.trim() ? prompt.trim() : process.cwd(),
+      sessionId: readHookText(parsed.sessionId ?? parsed.session_id)
+    };
   } catch {
-    if (stdin.trim())
-      return stdin.trim();
+    if (stdin.trim()) {
+      return {
+        agentName: process.env.MEMENTOS_AGENT_NAME,
+        query: stdin.trim()
+      };
+    }
   }
-  return process.cwd();
+  return {
+    agentName: process.env.MEMENTOS_AGENT_NAME,
+    query: process.cwd()
+  };
+}
+async function readInboxHookContext(input) {
+  if (!input.agentName)
+    return;
+  const response = await client.listInboxMessages({
+    agentName: input.agentName,
+    projectKey: input.projectKey,
+    sessionId: input.sessionId,
+    limit: 10
+  });
+  const messages = readInboxMessages(response);
+  if (messages.length === 0)
+    return;
+  await Promise.all(messages.map((message) => client.claimInboxMessage(message.id, { agentName: input.agentName })));
+  return formatInboxContext(messages);
+}
+function readInboxMessages(payload) {
+  if (typeof payload !== "object" || payload === null)
+    return [];
+  const messages = payload.messages;
+  if (!Array.isArray(messages))
+    return [];
+  return messages.flatMap((message) => {
+    if (typeof message !== "object" || message === null)
+      return [];
+    const record = message;
+    const id = readHookText(record.id);
+    const value = readHookText(record.message);
+    if (!id || !value)
+      return [];
+    return [{
+      id,
+      kind: readHookText(record.kind) ?? "directive",
+      message: value,
+      priority: readHookText(record.priority) ?? "normal",
+      title: readHookText(record.title)
+    }];
+  });
+}
+function formatInboxContext(messages) {
+  return [
+    "## mementos.md inbox",
+    "Apply these hosted agent directives before continuing. They have been claimed remotely.",
+    "",
+    ...messages.map((message) => `- [${message.priority}] ${message.title ? `${message.title}: ` : ""}${message.message} (${message.kind})`),
+    ""
+  ].join(`
+`);
+}
+function combineContextBlocks(...blocks) {
+  return blocks.map((block) => block?.trim()).filter(Boolean).join(`
+
+`);
+}
+function readHookText(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
 }
 async function readOptionalStdin() {
   if (process.stdin.isTTY)

package/dist/index.js

@@ -146,7 +146,7 @@ function readErrorMessage(payload, status) {
 }
 // src/mcp-runtime.ts
 import { createInterface } from "readline";
-var MEMENTOS_MCP_VERSION = "0.14.27";
+var MEMENTOS_MCP_VERSION = "0.14.29";
 var AUTHLESS_SCHEMA = {
   type: "object",
   properties: {},
@@ -358,6 +358,10 @@ function buildAgentSetupPlan(options = {}) {
   const hookCommand = "mementos hook stop";
   const injectCommand = "mementos inject";
   const files = [
+    {
+      path: join(baseDir, "mementos-instructions.md"),
+      content: renderSharedInstructions({ apiUrl, injectCommand, mcpCommand })
+    },
     {
       path: join(baseDir, "mementos-injection.md"),
       content: renderInjectionInstructions({ apiUrl, injectCommand })
@@ -374,6 +378,10 @@ function buildAgentSetupPlan(options = {}) {
     }
   ];
   for (const host of hosts) {
+    files.push({
+      path: join(baseDir, `${host}-instructions.md`),
+      content: renderHostInstructions(host, { apiUrl, injectCommand, mcpCommand })
+    });
     files.push({
       path: join(baseDir, `${host}.json`),
       content: `${JSON.stringify(renderHostConfig(host, { apiUrl, hookCommand, injectCommand, mcpCommand }), null, 2)}
@@ -498,11 +506,13 @@ function renderHostConfig(host, commands) {
     host,
     install: "bun install -g @hasna/mementos",
     remoteOnly: true,
+    nativeHooks: hasNativeHooks(host),
     mcp: renderMcpServerConfig(commands).mcpServers.mementos,
     hooks: {
       stop: commands.hookCommand,
       injection: commands.injectCommand
-    }
+    },
+    instructions: `${host}-instructions.md`
   };
 }
 function renderManagedHostConfig(host, commands) {
@@ -516,8 +526,15 @@ function renderManagedHostConfig(host, commands) {
       inject: commands.injectCommand,
       stopHook: commands.hookCommand
     },
+    injection: {
+      nativeHooks: hasNativeHooks(host),
+      fallbackCommand: commands.injectCommand,
+      mcpTools: ["memory.search", "memory.save", "memory.get", "memory.update", "memory.delete", "memory.usage"]
+    },
     files: {
       integrationDir: commands.baseDir,
+      sharedInstructions: join(commands.baseDir, "mementos-instructions.md"),
+      hostInstructions: join(commands.baseDir, `${host}-instructions.md`),
       injectionInstructions: join(commands.baseDir, "mementos-injection.md"),
       stopHook: join(commands.baseDir, "mementos-stop-hook.sh")
     }
@@ -798,6 +815,63 @@ MEMENTOS_API_URL=${apiUrl} MEMENTOS_API_TOKEN=$MEMENTOS_API_TOKEN ${injectComman
 This command reads hosted memory through the mementos.md API and prints a prompt-ready block.
 `;
 }
+function renderSharedInstructions({
+  apiUrl,
+  injectCommand,
+  mcpCommand
+}) {
+  return `# mementos.md Agent Instructions
+
+Use mementos.md as hosted durable memory for this agent host.
+
+- The MCP server command is \`${mcpCommand}\`.
+- The hosted API is \`${apiUrl}\`.
+- Use \`memory.search\` before non-trivial project work.
+- Use \`memory.save\` for durable decisions, root causes, and reusable context.
+- If the host does not provide a native hook, run \`${injectCommand} "<current task or question>"\` and include the returned hosted context in the next prompt.
+- Do not create or depend on a local memory database for the SaaS package.
+`;
+}
+function renderHostInstructions(host, commands) {
+  const common = renderSharedInstructions(commands);
+  if (host === "claude-code") {
+    return `${common}
+## Claude Code
+
+Claude Code has native mementos hooks installed by \`mementos setup agents\`.
+Use the mementos MCP server for explicit memory operations and let the
+\`UserPromptSubmit\`, \`SessionStart\`, and \`Stop\` hooks inject hosted context.
+`;
+  }
+  if (host === "codex") {
+    return `${common}
+## Codex
+
+Codex does not have a mementos native hook in its config file. Use the
+mementos MCP server for durable memory and run \`${commands.injectCommand}\`
+when you need prompt-ready hosted context before a turn.
+`;
+  }
+  if (host === "opencode") {
+    return `${common}
+## OpenCode
+
+Use the mementos MCP server for durable memory. When OpenCode cannot invoke a
+native lifecycle hook, run \`${commands.injectCommand}\` with the active task
+or error text and paste the hosted context into the next prompt.
+`;
+  }
+  return `${common}
+## Antigravity
+
+Use the mementos MCP server for durable memory. When Antigravity cannot invoke
+a native lifecycle hook, run \`${commands.injectCommand}\` with the active task
+or error text and include the hosted context before continuing.
+`;
+}
+function hasNativeHooks(host) {
+  return host === "claude-code";
+}
 function renderHookScript(command) {
   return `#!/usr/bin/env bash
 set -euo pipefail

package/dist/mcp-runtime.d.ts

@@ -1,5 +1,5 @@
 import { MementosRemoteClient } from "./remote-client";
-export declare const MEMENTOS_MCP_VERSION = "0.14.27";
+export declare const MEMENTOS_MCP_VERSION = "0.14.29";
 export interface RemoteMcpTool {
     name: string;
     description: string;

package/dist/mcp.js

@@ -151,7 +151,7 @@ function readErrorMessage(payload, status) {
 }
 
 // src/mcp-runtime.ts
-var MEMENTOS_MCP_VERSION = "0.14.27";
+var MEMENTOS_MCP_VERSION = "0.14.29";
 var AUTHLESS_SCHEMA = {
   type: "object",
   properties: {},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/mementos",
-  "version": "0.14.27",
+  "version": "0.14.29",
   "description": "Remote-only mementos.md SaaS CLI and MCP client",
   "type": "module",
   "main": "dist/index.js",