memento-mcp 0.3.16 → 0.3.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memento-mcp",
-  "version": "0.3.16",
+  "version": "0.3.18",
   "mcpName": "io.github.myrakrusemark/memento-protocol",
   "description": "The Memento Protocol — persistent memory for AI agents",
   "type": "module",

package/scripts/memento-instructions.sh

@@ -0,0 +1,55 @@
+#!/bin/bash
+# SessionStart hook (Memento) — inject MCP tool reference into every session.
+# Independent of identity/items injection — always runs.
+# Output: JSON with hookSpecificOutput.additionalContext.
+
+# Consume stdin (SessionStart sends JSON we don't need)
+cat > /dev/null
+
+read -r -d '' INSTRUCTIONS << 'MEMENTO_EOF'
+# Memento MCP (`mcp__memento__*`)
+
+**Load tools:** `ToolSearch query="+memento" max_results=20` — then READ the tool descriptions. They explain when and how to use each one.
+
+**Primary system:** Memento SaaS API (`https://memento-api.myrakrusemark.workers.dev`)
+**Dashboard:** `hifathom.com/dashboard`
+
+| Tool | What it does |
+|------|-------------|
+| `memento_init` | Initialize workspace (one-time setup) |
+| `memento_health` | System health — item/memory/skip counts, last updated |
+| `memento_read` / `memento_update` | Legacy markdown working memory (sections: active_work, standing_decisions, skip_list, session_notes) |
+| `memento_remember` | Store a memory (fact/decision/observation/instruction) with tags + expiration |
+| `memento_recall` | Search memories by keyword/tag/type — ranked by relevance |
+| `memento_consolidate` | Merge 3+ overlapping memories into one sharper representation |
+| `memento_skip_add` / `memento_skip_check` | Anti-memory: things to NOT investigate right now (with expiration) |
+| `memento_item_create` | Create structured item (active_work/standing_decision/skip_list/waiting_for/session_note) |
+| `memento_item_update` | Update item fields (status, next_action, priority, category, tags) |
+| `memento_item_delete` | Delete item (prefer archiving via status=archived) |
+| `memento_item_list` | List items with filters (category, status, query) |
+| `memento_identity` | Read identity crystal |
+| `memento_identity_update` | Write/replace identity crystal |
+
+**Memory discipline — notes are instructions, not logs.**
+Write: "Skip X until condition Y" — not "checked X, it was quiet."
+Every memory must answer: could a future agent with zero context read this and know exactly what to do?
+
+Use `memento_remember` when you learn something worth keeping.
+Use `memento_skip_add` for things to explicitly not re-investigate.
+Use `memento_recall` to search memories by keyword or tag.
+Hooks run automatically — recall before responses, distillation before compaction. Trust the hooks. Focus on writing good memories.
+
+REMINDER: If Memento MCP tools are not loaded, run: ToolSearch query="+memento" max_results=20
+MEMENTO_EOF
+
+python3 -c "
+import json, sys
+print(json.dumps({
+    'hookSpecificOutput': {
+        'hookEventName': 'SessionStart',
+        'additionalContext': sys.argv[1]
+    }
+}))
+" "$INSTRUCTIONS"
+
+exit 0

package/src/cli.js

@@ -9,7 +9,6 @@ import readline from "node:readline";
 import fs from "node:fs";
 import path from "node:path";
 import https from "node:https";
-import { execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { DEFAULTS } from "./config.js";
 
@@ -93,68 +92,6 @@ function httpsPost(url, body) {
   });
 }
 
-// ---------------------------------------------------------------------------
-// Instructions blob — used by headless integration and fallback print
-// ---------------------------------------------------------------------------
-
-const INSTRUCTIONS_BLOB = `## Memento Protocol
-
-Working memory is managed by Memento. MCP tools available:
-\`memento_remember\`, \`memento_recall\`, \`memento_item_list\`,
-\`memento_skip_add\`, \`memento_skip_check\`.
-
-**Memory discipline — notes are instructions, not logs.**
-Write: "Skip X until condition Y" — not "checked X, it was quiet."
-Every memory must answer: could a future agent with zero context
-read this and know exactly what to do?
-
-Use \`memento_remember\` when you learn something worth keeping.
-Use \`memento_skip_add\` for things to explicitly not re-investigate.
-Use \`memento_recall\` to search memories by keyword or tag.
-Hooks run automatically — recall before responses, distillation
-before compaction. Trust the hooks. Focus on writing good memories.`;
-
-// ---------------------------------------------------------------------------
-// Headless agent integration
-// ---------------------------------------------------------------------------
-
-const HEADLESS_CMDS = {
-  "claude-code": (prompt) => ["claude", "-p", "--dangerously-skip-permissions", prompt],
-  "gemini":      (prompt) => ["gemini", prompt],
-};
-
-function buildIntegrationPrompt(blob) {
-  return [
-    "The following instructions were generated by memento-mcp init for this project.",
-    "Add them to the file where you store persistent behavioral instructions",
-    "(e.g. CLAUDE.md for Claude Code). If the file exists, read it first and",
-    "integrate the new section without removing existing content. If a section",
-    "with the same heading already exists, replace it. If no instructions file",
-    "exists yet, create one.",
-    "",
-    "--- INSTRUCTIONS ---",
-    blob,
-    "--- END ---",
-  ].join("\n");
-}
-
-function runAgentHeadless(agentKey, prompt) {
-  const cmdBuilder = HEADLESS_CMDS[agentKey];
-  if (!cmdBuilder) return null;
-  const [cmd, ...args] = cmdBuilder(prompt);
-  try {
-    const result = execFileSync(cmd, args, {
-      cwd: process.cwd(),
-      encoding: "utf8",
-      stdio: ["pipe", "pipe", "inherit"],
-      timeout: 60000,
-    });
-    return result;
-  } catch {
-    return null;
-  }
-}
-
 // ---------------------------------------------------------------------------
 // CLI flag parsing
 // ---------------------------------------------------------------------------
@@ -492,11 +429,9 @@ async function runInit(flags = {}) {
   writeJsonFile(configPath, config);
   created.push(".memento.json");
 
-  // 7. Copy hook scripts — gated on any hook-supporting agent
-  const anyHookEnabled =
-    enableUserPrompt || enableStop || enablePreCompact || enableSessionStart;
-
-  if (hasHookAgent && anyHookEnabled) {
+  // 7. Copy hook scripts — gated on hook-supporting agent
+  // Instructions script is always copied; other hooks are gated on user selection
+  if (hasHookAgent) {
     const pkgScriptsDir = path.resolve(__dirname, "..", "scripts");
     const localScriptsDir = path.join(cwd, ".memento", "scripts");
     if (!fs.existsSync(localScriptsDir))
@@ -504,6 +439,7 @@ async function runInit(flags = {}) {
 
     const scriptFiles = [
       "hook-toast.sh",
+      "memento-instructions.sh",
       enableUserPrompt && "memento-userprompt-recall.sh",
       enableStop && "memento-stop-recall.sh",
       enablePreCompact && "memento-precompact-distill.sh",
@@ -526,6 +462,7 @@ async function runInit(flags = {}) {
     fs.writeFileSync(versionPath, pkgVersion + "\n");
 
     // Hook script commands (absolute paths)
+    const instructionsCmd = path.join(localScriptsDir, "memento-instructions.sh");
     const recallCmd = path.join(localScriptsDir, "memento-userprompt-recall.sh");
     const stopCmd = path.join(localScriptsDir, "memento-stop-recall.sh");
     const precompactCmd = path.join(localScriptsDir, "memento-precompact-distill.sh");
@@ -536,6 +473,8 @@ async function runInit(flags = {}) {
       const settingsPath = path.join(cwd, ".claude", "settings.local.json");
       const settings = readJsonFile(settingsPath) || {};
       let changed = false;
+      // Instructions hook always registered (not gated by enableSessionStart)
+      changed = ensureHook(settings, "SessionStart", instructionsCmd, 5000) || changed;
       if (enableUserPrompt) changed = ensureHook(settings, "UserPromptSubmit", recallCmd, 5000) || changed;
       if (enableStop) changed = ensureHook(settings, "Stop", stopCmd, 5000) || changed;
       if (enablePreCompact) changed = ensureHook(settings, "PreCompact", precompactCmd, 30000) || changed;
@@ -551,6 +490,8 @@ async function runInit(flags = {}) {
       const settingsPath = path.join(cwd, ".gemini", "settings.json");
       const settings = readJsonFile(settingsPath) || {};
       let changed = false;
+      // Instructions hook always registered
+      changed = ensureHook(settings, "SessionStart", instructionsCmd, 5000) || changed;
       if (enableUserPrompt) changed = ensureHook(settings, "BeforeAgent", recallCmd, 5000) || changed;
       if (enableStop) changed = ensureHook(settings, "SessionEnd", stopCmd, 5000) || changed;
       if (enablePreCompact) changed = ensureHook(settings, "PreCompress", precompactCmd, 30000) || changed;
@@ -610,57 +551,6 @@ async function runInit(flags = {}) {
     console.log(`  Non-interactive equivalent:\n    ${parts.join(" ")}\n`);
   }
 
-  // 12. Auto-integrate agent instructions
-  const primaryAgent = selectedAgents[0];
-  const prompt = buildIntegrationPrompt(INSTRUCTIONS_BLOB);
-  const cmdParts = HEADLESS_CMDS[primaryAgent]?.(prompt);
-
-  if (nonInteractive) {
-    // Auto-run headless integration, no prompt
-    if (cmdParts) {
-      console.log(`  Integrating instructions via ${AGENTS[primaryAgent].name}...`);
-      const result = runAgentHeadless(primaryAgent, prompt);
-      if (result !== null) {
-        console.log(result);
-      } else {
-        // Fallback: print the blob
-        console.log("  Agent integration failed — paste these instructions manually:\n");
-        printInstructionsFallback(selectedAgents);
-      }
-    } else {
-      printInstructionsFallback(selectedAgents);
-    }
-  } else {
-    // Interactive: ask with explicit command shown
-    if (cmdParts) {
-      const [cmd, ...args] = cmdParts;
-      const flagArgs = args.slice(0, -1).join(" ");
-      const displayCmd = `${cmd} ${flagArgs} <prompt>`;
-      const rl2 = readline.createInterface({ input: process.stdin, output: process.stdout });
-      console.log("─".repeat(60));
-      const integrate = await askYesNo(
-        rl2,
-        `\n  Auto-integrate instructions into your project?\n  This will run: ${displayCmd}\n\n  ⚠  This uses --dangerously-skip-permissions so the agent can\n  write to CLAUDE.md without prompting. If you prefer, decline\n  and we'll print the instructions for you to add manually.\n\n  Proceed?`,
-        true,
-      );
-      rl2.close();
-
-      if (integrate) {
-        console.log(`\n  Running ${AGENTS[primaryAgent].name}...`);
-        const result = runAgentHeadless(primaryAgent, prompt);
-        if (result !== null) {
-          console.log(result);
-        } else {
-          console.log("  Agent integration failed — paste these instructions manually:\n");
-          printInstructionsFallback(selectedAgents);
-        }
-      } else {
-        printInstructionsFallback(selectedAgents);
-      }
-    } else {
-      printInstructionsFallback(selectedAgents);
-    }
-  }
 }
 
 // ---------------------------------------------------------------------------
@@ -707,10 +597,11 @@ async function runUpdate() {
   const versionPath = path.join(cwd, ".memento", "version");
   fs.writeFileSync(versionPath, pkgVersion + "\n");
 
-  // Ensure SessionStart hook is registered for agents that support hooks
+  // Ensure SessionStart hooks are registered for agents that support hooks
   // Detect by config agents field or directory presence (older configs may lack agents)
   const config = readJsonFile(configPath) || {};
   const agents = config.agents || [];
+  const instructionsCmd = path.join(localScriptsDir, "memento-instructions.sh");
   const sessionStartCmd = path.join(localScriptsDir, "memento-sessionstart-identity.sh");
   const registeredHooks = [];
 
@@ -720,7 +611,9 @@ async function runUpdate() {
   if (hasClaude) {
     const settingsPath = path.join(cwd, ".claude", "settings.local.json");
     const settings = readJsonFile(settingsPath) || {};
-    if (ensureHook(settings, "SessionStart", sessionStartCmd, 10000)) {
+    let changed = ensureHook(settings, "SessionStart", instructionsCmd, 5000);
+    changed = ensureHook(settings, "SessionStart", sessionStartCmd, 10000) || changed;
+    if (changed) {
       writeJsonFile(settingsPath, settings);
       registeredHooks.push("Claude Code → .claude/settings.local.json");
     }
@@ -732,7 +625,9 @@ async function runUpdate() {
   if (hasGemini) {
     const settingsPath = path.join(cwd, ".gemini", "settings.json");
     const settings = readJsonFile(settingsPath) || {};
-    if (ensureHook(settings, "SessionStart", sessionStartCmd, 10000)) {
+    let changed = ensureHook(settings, "SessionStart", instructionsCmd, 5000);
+    changed = ensureHook(settings, "SessionStart", sessionStartCmd, 10000) || changed;
+    if (changed) {
       writeJsonFile(settingsPath, settings);
       registeredHooks.push("Gemini CLI → .gemini/settings.json");
     }
@@ -753,26 +648,6 @@ async function runUpdate() {
   console.log("  Restart your agent session to pick up changes.\n");
 }
 
-function printInstructionsFallback(selectedAgents) {
-  const hasNonClaude = selectedAgents.some((k) => k !== "claude-code");
-  const docTarget = hasNonClaude
-    ? "your CLAUDE.md, AGENTS.md, or equivalent"
-    : "your CLAUDE.md";
-
-  console.log("─".repeat(60));
-  console.log(`
-  One more step: paste the following into ${docTarget},
-  or hand it to your agent and ask it to add it. This teaches
-  your agent the memory discipline Memento expects.
-
-  ── paste below this line ──────────────────────────────
-
-${INSTRUCTIONS_BLOB}
-
-  ── paste above this line ──────────────────────────────
-`);
-}
-
 // ---------------------------------------------------------------------------
 // Entrypoint — only run when this module is the entry point (not imported)
 // ---------------------------------------------------------------------------