memoryai-mcp 2.3.0 → 2.3.1

package/dist/claude-setup.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * memoryai-claude-setup
+ *
+ * Wires MemoryAI into Claude Code at the MECHANISM level using HTTP hooks.
+ * Claude Code injects a hook's `additionalContext` straight into the model's
+ * context — no agent decision required — so memory works the moment it's set up,
+ * exactly like the OpenAI proxy. The user runs this once and never thinks about
+ * memory again:
+ *
+ *   - SessionStart    → POST /v1/hooks/claude/session-start  (inject DNA + recent context)
+ *   - UserPromptSubmit→ POST /v1/hooks/claude/user-prompt     (recall before answering)
+ *   - Stop            → POST /v1/hooks/claude/stop            (auto-store after each turn)
+ *
+ * It also registers the MCP server (so the 70+ tools are available for advanced
+ * use) and writes a CLAUDE.md note. Existing settings/CLAUDE.md are merged, never
+ * clobbered.
+ */
+export {};

package/dist/claude-setup.js

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+/**
+ * memoryai-claude-setup
+ *
+ * Wires MemoryAI into Claude Code at the MECHANISM level using HTTP hooks.
+ * Claude Code injects a hook's `additionalContext` straight into the model's
+ * context — no agent decision required — so memory works the moment it's set up,
+ * exactly like the OpenAI proxy. The user runs this once and never thinks about
+ * memory again:
+ *
+ *   - SessionStart    → POST /v1/hooks/claude/session-start  (inject DNA + recent context)
+ *   - UserPromptSubmit→ POST /v1/hooks/claude/user-prompt     (recall before answering)
+ *   - Stop            → POST /v1/hooks/claude/stop            (auto-store after each turn)
+ *
+ * It also registers the MCP server (so the 70+ tools are available for advanced
+ * use) and writes a CLAUDE.md note. Existing settings/CLAUDE.md are merged, never
+ * clobbered.
+ */
+import { createInterface } from "node:readline";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+const rl = createInterface({ input: process.stdin, output: process.stdout });
+function ask(question, fallback) {
+    const suffix = fallback ? ` [${fallback}]` : "";
+    return new Promise((resolve) => {
+        rl.question(`${question}${suffix}: `, (answer) => {
+            resolve(answer.trim() || fallback || "");
+        });
+    });
+}
+function readJsonSafe(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        return JSON.parse(readFileSync(path, "utf-8")) || {};
+    }
+    catch {
+        console.error(`  warn  ${path} is not valid JSON — leaving it untouched and aborting.`);
+        process.exit(1);
+    }
+}
+function writeJson(path, data) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(data, null, 2) + "\n", "utf-8");
+}
+/** A single HTTP hook handler bound to a MemoryAI endpoint. */
+function httpHook(endpoint, apiKey, timeout) {
+    return {
+        type: "http",
+        url: endpoint,
+        timeout,
+        headers: { Authorization: `Bearer ${apiKey}` },
+        // Required for Claude Code to interpolate the env-style header value.
+        allowedEnvVars: [],
+    };
+}
+/** True if any handler in a hook group already points at a memoryai endpoint. */
+function groupHasMemoryAI(group) {
+    const handlers = (group && group.hooks) || [];
+    return handlers.some((h) => typeof h?.url === "string" && h.url.includes("/v1/hooks/claude/"));
+}
+function ensureHook(settings, event, handler) {
+    settings.hooks = settings.hooks || {};
+    settings.hooks[event] = settings.hooks[event] || [];
+    // De-dupe: skip if a MemoryAI hook for this event already exists.
+    if (settings.hooks[event].some(groupHasMemoryAI))
+        return false;
+    settings.hooks[event].push({ hooks: [handler] });
+    return true;
+}
+const CLAUDE_MD = `
+# MemoryAI — Persistent Memory (automatic)
+
+MemoryAI is wired into this Claude Code via HTTP hooks, so memory works
+automatically at the mechanism level — you don't have to call tools by hand:
+
+- Relevant past context is injected before each prompt (UserPromptSubmit hook).
+- Session-start context (preferences, decisions, recent work) loads on open.
+- Decisions and preferences are stored automatically when each turn ends.
+
+The MemoryAI MCP server is also connected for advanced use. You may call
+\`memory_recall\` explicitly when you need deeper history, but for everyday work
+the hooks handle it. Never store secrets or credentials.
+`;
+const MCP_BLOCK = (apiKey, endpoint) => ({
+    command: "npx",
+    args: ["-y", "memoryai-mcp"],
+    env: { HM_API_KEY: apiKey, HM_ENDPOINT: endpoint },
+});
+/**
+ * Auto-provision a fresh API key from the public self-service endpoint so the
+ * user truly does nothing — no curl, no dashboard. Returns the key string, or
+ * null on any failure (caller falls back to asking). The endpoint is public and
+ * IP-rate-limited server-side; we accept ToS on the user's behalf since running
+ * this installer is an explicit action.
+ */
+async function provisionKey(endpoint, name) {
+    const base = endpoint.replace(/\/+$/, "");
+    try {
+        const resp = await fetch(`${base}/v1/admin/provision`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ name: name || "claude-code", tos_accepted: true }),
+        });
+        if (!resp.ok) {
+            const txt = await resp.text().catch(() => "");
+            console.error(`  warn  auto-provision failed (HTTP ${resp.status}). ${txt.slice(0, 200)}`);
+            return null;
+        }
+        const data = (await resp.json());
+        if (data?.api_key) {
+            console.log(`  ok    provisioned new API key (${String(data.api_key).slice(0, 10)}…, plan=${data.plan || "?"})`);
+            return data.api_key;
+        }
+        return null;
+    }
+    catch (e) {
+        console.error(`  warn  auto-provision request error: ${e instanceof Error ? e.message : String(e)}`);
+        return null;
+    }
+}
+async function main() {
+    console.log(`\nMemoryAI — Claude Code Setup (mechanism-level auto-memory)\n`);
+    // Non-interactive fast path: if everything is supplied via env, skip prompts.
+    // MEMORYAI_SCOPE = "user" (default) or "project". Enables CI / scripted installs.
+    const envKey = process.env.HM_API_KEY || process.env.MEMORYAI_API_KEY || "";
+    const envEndpoint = process.env.HM_ENDPOINT || process.env.MEMORYAI_ENDPOINT || "";
+    const envScope = (process.env.MEMORYAI_SCOPE || "").toLowerCase();
+    const nonInteractive = process.env.MEMORYAI_NONINTERACTIVE === "1" || (Boolean(envKey) && Boolean(envEndpoint));
+    let apiKey;
+    let endpoint;
+    let scopeAns;
+    if (nonInteractive) {
+        endpoint = envEndpoint || "https://memoryai.dev";
+        scopeAns = envScope || "u";
+        apiKey = envKey;
+        if (!apiKey) {
+            console.log("  ...  non-interactive, no key — provisioning one");
+            const provisioned = await provisionKey(endpoint, "claude-code");
+            if (provisioned)
+                apiKey = provisioned;
+        }
+        else {
+            console.log("  (non-interactive: using environment configuration)");
+        }
+    }
+    else {
+        endpoint = await ask("Endpoint", envEndpoint || "https://memoryai.dev");
+        apiKey = envKey || (await ask("MemoryAI API key (blank = auto-provision a free one)")).trim();
+        if (!apiKey) {
+            console.log("  ...  no key given — provisioning one for you");
+            const provisioned = await provisionKey(endpoint, "claude-code");
+            if (provisioned)
+                apiKey = provisioned;
+        }
+        scopeAns = (await ask("Apply to (u)ser globally or this (p)roject?", "u")).toLowerCase();
+    }
+    if (!apiKey) {
+        console.error("Error: could not obtain an API key (auto-provision failed). Set HM_API_KEY and re-run.");
+        process.exit(1);
+    }
+    const settingsPath = scopeAns.startsWith("p")
+        ? join(process.cwd(), ".claude", "settings.json")
+        : join(homedir(), ".claude", "settings.json");
+    console.log("");
+    const settings = readJsonSafe(settingsPath);
+    // 1. MCP server (advanced tools)
+    settings.mcpServers = settings.mcpServers || {};
+    if (!settings.mcpServers.memoryai) {
+        settings.mcpServers.memoryai = MCP_BLOCK(apiKey, endpoint);
+        console.log("  add   mcpServers.memoryai");
+    }
+    else {
+        console.log("  skip  mcpServers.memoryai (already present)");
+    }
+    // 2. The three lifecycle hooks. UserPromptSubmit gets a tighter timeout
+    //    because it blocks the prompt until it returns.
+    const base = endpoint.replace(/\/+$/, "");
+    const added = {
+        SessionStart: ensureHook(settings, "SessionStart", httpHook(`${base}/v1/hooks/claude/session-start`, apiKey, 10)),
+        UserPromptSubmit: ensureHook(settings, "UserPromptSubmit", httpHook(`${base}/v1/hooks/claude/user-prompt`, apiKey, 10)),
+        Stop: ensureHook(settings, "Stop", httpHook(`${base}/v1/hooks/claude/stop`, apiKey, 15)),
+    };
+    for (const [event, didAdd] of Object.entries(added)) {
+        console.log(`  ${didAdd ? "add  " : "skip "} hooks.${event}${didAdd ? "" : " (already present)"}`);
+    }
+    writeJson(settingsPath, settings);
+    console.log(`  write ${settingsPath}`);
+    // 3. CLAUDE.md note (append if missing).
+    const claudeMdPath = scopeAns.startsWith("p")
+        ? join(process.cwd(), "CLAUDE.md")
+        : join(homedir(), ".claude", "CLAUDE.md");
+    const existing = existsSync(claudeMdPath) ? readFileSync(claudeMdPath, "utf-8") : "";
+    if (!existing.includes("MemoryAI — Persistent Memory")) {
+        writeFileSync(claudeMdPath, existing + (existing ? "\n" : "") + CLAUDE_MD, "utf-8");
+        console.log(`  ${existing ? "append" : "create"} ${claudeMdPath}`);
+    }
+    else {
+        console.log(`  skip  ${claudeMdPath} (note already present)`);
+    }
+    console.log(`
+Done. MemoryAI runs automatically in Claude Code — nothing else to do.
+  - Context is recalled before each prompt and injected for you.
+  - Decisions/preferences are stored when each turn ends.
+
+Next steps:
+  1. Restart Claude Code (loads the hooks + MCP server).
+  2. Just work normally. Memory persists across sessions on its own.
+`);
+    rl.close();
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/index.js

@@ -11,10 +11,43 @@ import { z } from "zod";
 const API_URL = process.env.MEMORYAI_ENDPOINT || process.env.HM_ENDPOINT || "http://localhost:8420";
 const API_KEY = process.env.MEMORYAI_API_KEY || process.env.HM_API_KEY || "";
 const REQUEST_TIMEOUT_MS = 30_000; // P2 #6: 30s default timeout for API requests
-// Context Guard — per-IDE settings via env vars (MEMORYAI_ preferred, HM_ backward compat)
+// Context Guard — per-IDE settings via env vars.
+// HM_COMPACT_AT and HM_CRITICAL_AT are now ABSOLUTE token counts (e.g. "100000",
+// "150000"). The legacy meaning ("30" = 30%) is detected automatically: any
+// value < 1000 is treated as a deprecated percentage and converted to absolute
+// using HM_CONTEXT_CAP if present, otherwise the value is sent as-is and the
+// server interprets it as a fraction (backward-compat path).
+//
+// HM_CONTEXT_CAP itself is no longer required — users set the two thresholds
+// directly. When present it is forwarded as max_tokens so the server can clamp.
 const CG_CONTEXT_CAP = parseInt(process.env.MEMORYAI_CONTEXT_CAP || process.env.HM_CONTEXT_CAP || "0", 10);
-const CG_COMPACT_PCT = parseInt(process.env.MEMORYAI_COMPACT_AT || process.env.HM_COMPACT_AT || "0", 10);
-const CG_CRITICAL_PCT = parseInt(process.env.MEMORYAI_CRITICAL_AT || process.env.HM_CRITICAL_AT || "0", 10);
+const CG_COMPACT_RAW = parseInt(process.env.MEMORYAI_COMPACT_AT || process.env.HM_COMPACT_AT || "0", 10);
+const CG_CRITICAL_RAW = parseInt(process.env.MEMORYAI_CRITICAL_AT || process.env.HM_CRITICAL_AT || "0", 10);
+// Heuristic: small numbers are legacy percentages; large numbers are absolute tokens.
+// Threshold "<= 100" is generous enough to catch any sensible % (max 95%) and
+// well below any sensible absolute count (min would be ~10K tokens).
+function _isLegacyPct(v) { return v > 0 && v <= 100; }
+// Resolved absolute thresholds. 0 means "not configured — use server defaults".
+const CG_COMPACT_AT_TOKENS = (() => {
+    if (CG_COMPACT_RAW <= 0)
+        return 0;
+    if (_isLegacyPct(CG_COMPACT_RAW) && CG_CONTEXT_CAP > 0) {
+        return Math.round((CG_COMPACT_RAW / 100) * CG_CONTEXT_CAP);
+    }
+    return _isLegacyPct(CG_COMPACT_RAW) ? 0 : CG_COMPACT_RAW;
+})();
+const CG_CRITICAL_AT_TOKENS = (() => {
+    if (CG_CRITICAL_RAW <= 0)
+        return 0;
+    if (_isLegacyPct(CG_CRITICAL_RAW) && CG_CONTEXT_CAP > 0) {
+        return Math.round((CG_CRITICAL_RAW / 100) * CG_CONTEXT_CAP);
+    }
+    return _isLegacyPct(CG_CRITICAL_RAW) ? 0 : CG_CRITICAL_RAW;
+})();
+// Legacy decimal % path for the rare case where user keeps "30/50" without
+// HM_CONTEXT_CAP — server still accepts compact_pct/critical_pct as decimals.
+const CG_COMPACT_PCT = _isLegacyPct(CG_COMPACT_RAW) && CG_CONTEXT_CAP <= 0 ? CG_COMPACT_RAW : 0;
+const CG_CRITICAL_PCT = _isLegacyPct(CG_CRITICAL_RAW) && CG_CONTEXT_CAP <= 0 ? CG_CRITICAL_RAW : 0;
 // --- HTTP helper ---
 async function api(method, path, body) {
     const resp = await fetch(`${API_URL}${path}`, {
@@ -829,21 +862,34 @@ server.tool("context_guard_check", "[CORE] Check context pressure — returns re
             max_tokens: maxTokens,
             model: args.model || null,
         };
-        // Send per-IDE threshold overrides if configured via env vars
+        // Per-IDE threshold overrides. Absolute (CG_*_AT_TOKENS) is preferred —
+        // server treats it as the authoritative trigger. Decimal % is the
+        // backward-compat path for users whose env still says "30/50".
+        if (CG_COMPACT_AT_TOKENS > 0)
+            payload.compact_at_tokens = CG_COMPACT_AT_TOKENS;
+        if (CG_CRITICAL_AT_TOKENS > 0)
+            payload.critical_at_tokens = CG_CRITICAL_AT_TOKENS;
         if (CG_COMPACT_PCT > 0)
             payload.compact_pct = CG_COMPACT_PCT / 100;
         if (CG_CRITICAL_PCT > 0)
             payload.critical_pct = CG_CRITICAL_PCT / 100;
         const r = (await api("POST", "/v1/context/guard/check", payload));
-        const pct = r.usage_percent;
+        // Render against the user's configured critical threshold so the bar is
+        // anchored to the absolute trigger point (HM_CRITICAL_AT), not a soft
+        // model-window percentage. When critical_at_tokens is missing, fall back
+        // to the legacy usage_percent rendering.
+        const tokens = args.estimated_tokens;
+        const critical = r.critical_at_tokens || (CG_CRITICAL_AT_TOKENS > 0 ? CG_CRITICAL_AT_TOKENS : 0);
+        const compact = r.compact_at_tokens || (CG_COMPACT_AT_TOKENS > 0 ? CG_COMPACT_AT_TOKENS : 0);
         const barLen = 20;
-        const filled = Math.round(pct / 100 * barLen);
+        const ratio = critical > 0 ? Math.min(1, tokens / critical) : (r.usage_percent / 100);
+        const filled = Math.max(0, Math.min(barLen, Math.round(ratio * barLen)));
         const bar = "\u2588".repeat(filled) + "\u2591".repeat(barLen - filled);
         return ok(`Context Guard v6:\n` +
-            `[${bar}] ${pct.toFixed(1)}%\n` +
-            `Recommendation: ${r.recommendation.toUpperCase()}${r.should_compact ? " — compact now" : ""}\n` +
+            `[${bar}] ${tokens.toLocaleString()} / ${critical ? critical.toLocaleString() + " tokens" : (r.usage_percent.toFixed(1) + "%")}\n` +
+            `Recommendation: ${r.recommendation.toUpperCase()}${r.should_compact ? " \u2014 compact now" : ""}\n` +
             `Urgency: ${r.urgency}\n` +
-            `Thresholds: compact=${r.compact_at_tokens.toLocaleString()}, critical=${r.critical_at_tokens.toLocaleString()}\n` +
+            `Thresholds: compact=${(compact || r.compact_at_tokens).toLocaleString()}, critical=${(critical || r.critical_at_tokens).toLocaleString()}\n` +
             `DNA memories: ${r.dna_memories} | Hot: ${r.hot_memories} | Stale: ${r.stale_memories}\n` +
             `Bootstrap ready: ${r.bootstrap_ready ? "yes" : "no"}\n` +
             (r.last_compact_minutes_ago != null ? `Last compact: ${r.last_compact_minutes_ago.toFixed(0)} min ago` : "No compacts yet"));
@@ -874,6 +920,56 @@ server.tool("context_guard_compact", "[CORE] Save context to long-term memory wh
         return err(e);
     }
 });
+// ide_turn_check — server-authoritative context guard (zero guessing)
+// The agent cannot read its host IDE's actual context window from inside an
+// MCP tool. Instead of asking it to estimate tokens, this tool only asks for
+// turn_count + max_tokens and the server does the math. Returns a ready-to-
+// follow action_prompt — agent reads it verbatim, no interpretation needed.
+server.tool("ide_turn_check", "[CORE] Server-authoritative context check for IDE hooks. Pass turn_count + max_tokens; server computes pressure and returns an action_prompt the agent should follow verbatim. Use this instead of context_guard_check from IDE auto-capture hooks.", {
+    turn_count: z.number().describe("Number of assistant turns in this conversation."),
+    max_tokens: z.number().optional().describe("Actual IDE context window in tokens — NOT the underlying model claim. Default 200000."),
+    avg_tokens_per_turn: z.number().optional().describe("Calibration knob, default 4000."),
+    skip_below_turns: z.number().optional().describe("Skip the check below this many turns (default 20)."),
+    model: z.string().optional().describe("Optional model hint when max_tokens not set."),
+}, async (args) => {
+    try {
+        const payload = {
+            turn_count: args.turn_count,
+            max_tokens: args.max_tokens ?? CG_CONTEXT_CAP ?? 200_000,
+            avg_tokens_per_turn: args.avg_tokens_per_turn ?? 8000,
+            skip_below_turns: args.skip_below_turns ?? 10,
+            model: args.model ?? null,
+        };
+        // Per-IDE threshold overrides. Absolute first (preferred), % fallback.
+        if (CG_COMPACT_AT_TOKENS > 0)
+            payload.compact_at_tokens = CG_COMPACT_AT_TOKENS;
+        if (CG_CRITICAL_AT_TOKENS > 0)
+            payload.critical_at_tokens = CG_CRITICAL_AT_TOKENS;
+        if (CG_COMPACT_PCT > 0)
+            payload.compact_pct = CG_COMPACT_PCT / 100;
+        if (CG_CRITICAL_PCT > 0)
+            payload.critical_pct = CG_CRITICAL_PCT / 100;
+        const r = (await api("POST", "/v1/ide/guard/turn-check", payload));
+        if (r.skipped) {
+            return ok(`Turn check skipped (turn ${args.turn_count} below threshold). Recommendation: SAFE.`);
+        }
+        const tokens = r.estimated_tokens;
+        const critical = r.critical_at_tokens || (CG_CRITICAL_AT_TOKENS > 0 ? CG_CRITICAL_AT_TOKENS : 0);
+        const barLen = 20;
+        const ratio = critical > 0 ? Math.min(1, tokens / critical) : (r.usage_percent / 100);
+        const filled = Math.max(0, Math.min(barLen, Math.round(ratio * barLen)));
+        const bar = "\u2588".repeat(filled) + "\u2591".repeat(barLen - filled);
+        return ok(`IDE Turn Check (server-authoritative):\n` +
+            `[${bar}] ${tokens.toLocaleString()} / ${critical ? critical.toLocaleString() + " tokens" : (r.usage_percent.toFixed(1) + "%")}\n` +
+            `Recommendation: ${r.recommendation.toUpperCase()}\n` +
+            `Urgency: ${r.urgency}\n` +
+            `Thresholds: compact=${r.compact_at_tokens.toLocaleString()}, critical=${r.critical_at_tokens.toLocaleString()}\n` +
+            (r.action_prompt ? `\nACTION FOR AGENT (follow verbatim):\n${r.action_prompt}` : "No action needed."));
+    }
+    catch (e) {
+        return err(e);
+    }
+});
 // context_guard_bootstrap — DNA-first session bootstrap (IDE)
 server.tool("context_guard_bootstrap", "Advanced: Load context from previous sessions at session start. Returns preferences, recent activity, and task-relevant memories. Call once at the beginning of a session to restore context.", {
     task: z.string().describe("Task description for context relevance"),

package/dist/kiro-setup.d.ts

@@ -1,7 +1,16 @@
 #!/usr/bin/env node
 /**
  * memoryai-kiro-setup
- * Zero-dependency setup script that creates .kiro/settings/mcp.json
- * and .kiro/steering/memoryai.md in the current project directory.
+ * Zero-dependency setup script that creates, in the current project:
+ *   - .kiro/settings/mcp.json            (MCP server wiring)
+ *   - .kiro/steering/memoryai.md         (always-on instructions, soft fallback)
+ *   - .kiro/hooks/memoryai-auto-recall.kiro.hook   (promptSubmit → bootstrap/recall)
+ *   - .kiro/hooks/memoryai-auto-capture.kiro.hook  (agentStop → store/compact)
+ *
+ * The two hooks are what make memory TRULY automatic: they fire on IDE events
+ * (every prompt / end of every turn) instead of relying on the agent to
+ * remember the steering instructions. Result: the user installs once and never
+ * has to think about memory again — recall happens before answers, persistence
+ * happens after turns, compaction happens when context fills.
  */
 export {};

package/dist/kiro-setup.js

@@ -1,12 +1,21 @@
 #!/usr/bin/env node
 /**
  * memoryai-kiro-setup
- * Zero-dependency setup script that creates .kiro/settings/mcp.json
- * and .kiro/steering/memoryai.md in the current project directory.
+ * Zero-dependency setup script that creates, in the current project:
+ *   - .kiro/settings/mcp.json            (MCP server wiring)
+ *   - .kiro/steering/memoryai.md         (always-on instructions, soft fallback)
+ *   - .kiro/hooks/memoryai-auto-recall.kiro.hook   (promptSubmit → bootstrap/recall)
+ *   - .kiro/hooks/memoryai-auto-capture.kiro.hook  (agentStop → store/compact)
+ *
+ * The two hooks are what make memory TRULY automatic: they fire on IDE events
+ * (every prompt / end of every turn) instead of relying on the agent to
+ * remember the steering instructions. Result: the user installs once and never
+ * has to think about memory again — recall happens before answers, persistence
+ * happens after turns, compaction happens when context fills.
  */
 import { createInterface } from "node:readline";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { join, dirname } from "node:path";
 const rl = createInterface({ input: process.stdin, output: process.stdout });
 function ask(question, fallback) {
     const suffix = fallback ? ` [${fallback}]` : "";
@@ -21,12 +30,42 @@ function writeIfMissing(filePath, content, label) {
         console.log(`  skip  ${label} (already exists)`);
         return false;
     }
-    const dir = filePath.substring(0, filePath.lastIndexOf("/"));
+    const dir = dirname(filePath);
     mkdirSync(dir, { recursive: true });
     writeFileSync(filePath, content, "utf-8");
     console.log(`  create  ${label}`);
     return true;
 }
+/**
+ * Auto-provision a fresh API key from the public self-service endpoint so the
+ * user does nothing — no curl, no dashboard. Returns the key, or null on
+ * failure (caller falls back to asking). Public + IP-rate-limited server-side.
+ */
+async function provisionKey(endpoint, name) {
+    const base = endpoint.replace(/\/+$/, "");
+    try {
+        const resp = await fetch(`${base}/v1/admin/provision`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ name: name || "kiro", tos_accepted: true }),
+        });
+        if (!resp.ok) {
+            const txt = await resp.text().catch(() => "");
+            console.error(`  warn  auto-provision failed (HTTP ${resp.status}). ${txt.slice(0, 200)}`);
+            return null;
+        }
+        const data = (await resp.json());
+        if (data?.api_key) {
+            console.log(`  ok    provisioned new API key (${String(data.api_key).slice(0, 10)}…, plan=${data.plan || "?"})`);
+            return data.api_key;
+        }
+        return null;
+    }
+    catch (e) {
+        console.error(`  warn  auto-provision request error: ${e instanceof Error ? e.message : String(e)}`);
+        return null;
+    }
+}
 const MCP_CONFIG = (apiKey, endpoint) => JSON.stringify({
     mcpServers: {
         memoryai: {
@@ -36,76 +75,120 @@ const MCP_CONFIG = (apiKey, endpoint) => JSON.stringify({
                 HM_API_KEY: apiKey,
                 HM_ENDPOINT: endpoint,
             },
+            // Auto-approve the everyday memory tools so the hooks can run them
+            // without prompting the user — this is what makes memory truly
+            // hands-off. These are all low-risk (read + append-only store +
+            // context bookkeeping); no destructive operations are listed.
+            autoApprove: [
+                "memory_bootstrap",
+                "memory_recall",
+                "memory_store",
+                "memory_recover",
+                "context_guard_check",
+                "context_guard_compact",
+                "ide_turn_check",
+                "memory_pitfall_check",
+            ],
         },
     },
 }, null, 2) + "\n";
-const STEERING = `---
-inclusion: always
----
-
-# MemoryAI — Persistent Memory Instructions
-
-You have access to MemoryAI tools via MCP. Use them to maintain long-term memory across sessions.
-
-## Session Start
-
-Call \`memory_bootstrap\` at the beginning of every session to load prior context.
-If bootstrap returns nothing, call \`memory_recover\` to check for recent session state.
-
-## During Work
-
-- Before answering questions about past decisions, architecture, or preferences: call \`memory_recall\` with a relevant query.
-- After making a significant decision, completing a task, or learning something about the codebase: call \`memory_store\` with appropriate \`memory_type\`:
-  - \`decision\` — architectural or technical decisions (DNA-protected, never decays)
-  - \`preference\` — user preferences and conventions (DNA-protected, never decays)
-  - \`fact\` — codebase facts, API details, configs
-  - \`error\` — lessons learned from mistakes
-  - \`goal\` — current objectives and milestones
-- After learning from a mistake or unexpected result: call \`learn\` with action, result, and lesson fields.
-
-## Entity Tracking
-
-When you create, modify, or reference important files, packages, or people:
-1. Call \`entity_list\` to check if already tracked
-2. If not tracked, call \`memory_store\` with \`memory_type=entity\`
-
-## Memory Health
-
-If a session is running long, call \`memory_health\` to check working memory usage.
-If above 80%, call \`memory_compact\` proactively to consolidate context.
-
-## Session End
-
-When wrapping up or when the agent is about to stop:
-1. Call \`memory_compact\` to consolidate the session's context into durable memories
-2. Call \`memory_store\` with a brief summary of what was accomplished
-
-## Rules
-
-- Recall only when past context is actually needed — not on every message
-- Store important outcomes after completing tasks, not after every interaction
-- Present memories naturally — integrate recalled info into responses, don't show raw API output
-- Use \`zone: "critical"\` for decisions that must never be forgotten
-- Use \`retention: "forever"\` for permanent project knowledge
+const STEERING = `---
+inclusion: always
+---
+
+# MemoryAI — Persistent Memory (mostly automatic)
+
+You have MemoryAI tools via MCP. Two Agent Hooks automate the common path:
+- **Auto-Recall** (on every prompt) loads memory before you answer.
+- **Auto-Capture** (end of every turn) stores important memory and compacts when full.
+
+So you normally do NOT need to manage memory by hand. This file is a fallback
+for cases the hooks don't cover, plus the rules for HOW to use memory well.
+
+## What the hooks already handle
+- Session-start \`memory_bootstrap\`, per-prompt \`memory_recall\`.
+- Post-turn \`memory_store\` for decisions/preferences/facts/pitfalls/procedures.
+- \`context_guard_check\` → \`context_guard_compact\` when context fills.
+
+Don't duplicate these on your own unless a hook clearly didn't run.
+
+## Memory types
+- \`decision\` — architectural/technical decisions (DNA-protected, never decays)
+- \`preference\` — user preferences and conventions (DNA-protected)
+- \`fact\` — codebase facts, API details, configs
+- \`pitfall\` — a mistake + its lesson (DNA-protected)
+- \`procedure\` — a reusable workflow (DNA-protected)
+- \`error\` / \`goal\` — lessons and current objectives
+
+## Rules
+- Recall only when past context is actually needed — not on every trivial message.
+- Store important outcomes, not every interaction. Dedup is automatic.
+- Integrate recalled info naturally; never show raw tool output.
+- Never store secrets, credentials, tokens, or full API keys.
+- Use \`zone: "critical"\` for things that must never be forgotten.
+- Use \`retention: "forever"\` for permanent project knowledge.
 `;
+// ── Agent Hooks — event-level automation (the real "zero-action" layer) ──
+// These fire on IDE events so memory works even if the agent ignores steering.
+const HOOK_AUTO_RECALL = JSON.stringify({
+    enabled: true,
+    name: "MemoryAI Auto-Recall",
+    description: "Before answering each user message, automatically load relevant memory so the agent always has prior context — zero user action.",
+    version: "1",
+    when: { type: "promptSubmit" },
+    then: {
+        type: "askAgent",
+        prompt: "Before responding, ensure you have the relevant long-term memory (do this silently, integrate naturally, never show raw tool output):\n\n" +
+            "1. If this is the first turn of the session, call memory_bootstrap once to load preferences, decisions, and recent project context.\n" +
+            "2. If the user's message references past work, decisions, preferences, or anything that might be stored (\"what did we\", \"last time\", \"our approach\", \"why did we\", or a question about the project), call memory_recall with a focused query first, then answer using what you find.\n" +
+            "3. If the message is trivial small-talk, skip recall.\n\n" +
+            "Use recalled memory to inform the answer; do not announce that a memory system exists unless asked.",
+    },
+}, null, 2) + "\n";
+const HOOK_AUTO_CAPTURE = JSON.stringify({
+    enabled: true,
+    name: "MemoryAI Auto-Capture",
+    description: "Fully automatic: persist memorable events to MemoryAI after every turn, and persist session state silently when pressure thresholds hit. No user action ever required — the IDE host handles window eviction on its own and the auto-recall hook rehydrates context afterwards.",
+    version: "5",
+    when: { type: "agentStop" },
+    then: {
+        type: "askAgent",
+        prompt: "Run two background tasks SILENTLY. Do not tell the user about either task, do not change your normal reply, do not suggest /compact or 'open a new conversation' — those are not user actions in this design.\n\n" +
+            "1. PERSIST: If the turn produced a decision, preference, important project fact, lesson from a mistake (pitfall), or reusable procedure, call memory_store with the correct memory_type. Skip greetings and trivia. Dedup is automatic. Never store secrets.\n\n" +
+            "2. RELEASE CHECK: Count the assistant turns in this conversation, then call ide_turn_check with turn_count = (your count) and max_tokens = 200000. Read the response's action_prompt field and follow it VERBATIM. Every action_prompt in this design tells you to act SILENTLY — call context_guard_compact when asked, do nothing when asked. Never message the user from this hook.\n\n" +
+            "The design: MemoryAI persists to DB on threshold; the IDE host (Kiro auto-summarize, Claude Code /clear, Cursor /reset) evicts the window on its own schedule; the auto-recall hook on the next user message rehydrates context. From the user's view, nothing ever happens — the chat just keeps working.",
+    },
+}, null, 2) + "\n";
 async function main() {
     const cwd = process.cwd();
     console.log(`\nMemoryAI Kiro Setup`);
     console.log(`Project: ${cwd}\n`);
-    const apiKey = process.env.HM_API_KEY || (await ask("MemoryAI API key (hm_sk_...)"));
+    const endpoint = await ask("Endpoint", process.env.HM_ENDPOINT || "https://memoryai.dev");
+    let apiKey = process.env.HM_API_KEY || (await ask("MemoryAI API key (blank = auto-provision a free one)")).trim();
     if (!apiKey) {
-        console.error("Error: API key is required. Set HM_API_KEY or enter it above.");
+        console.log("  ...  no key given — provisioning one for you");
+        const provisioned = await provisionKey(endpoint, "kiro");
+        if (provisioned)
+            apiKey = provisioned;
+    }
+    if (!apiKey) {
+        console.error("Error: could not obtain an API key (auto-provision failed). Set HM_API_KEY and re-run.");
         process.exit(1);
     }
-    const endpoint = await ask("Endpoint", process.env.HM_ENDPOINT || "https://memoryai.dev");
     console.log("");
     writeIfMissing(join(cwd, ".kiro", "settings", "mcp.json"), MCP_CONFIG(apiKey, endpoint), ".kiro/settings/mcp.json");
     writeIfMissing(join(cwd, ".kiro", "steering", "memoryai.md"), STEERING, ".kiro/steering/memoryai.md");
-    console.log(`
-Done. Next steps:
-  1. Restart Kiro
-  2. Ask: "What do you remember about this project?"
-  3. The agent should call memory_bootstrap automatically
+    writeIfMissing(join(cwd, ".kiro", "hooks", "memoryai-auto-recall.kiro.hook"), HOOK_AUTO_RECALL, ".kiro/hooks/memoryai-auto-recall.kiro.hook");
+    writeIfMissing(join(cwd, ".kiro", "hooks", "memoryai-auto-capture.kiro.hook"), HOOK_AUTO_CAPTURE, ".kiro/hooks/memoryai-auto-capture.kiro.hook");
+    console.log(`
+Done. MemoryAI now runs automatically — you don't have to do anything.
+  - Auto-Recall hook loads relevant memory before each answer.
+  - Auto-Capture hook stores decisions/preferences and compacts when full.
+
+Next steps:
+  1. Restart Kiro (loads the MCP server + hooks)
+  2. Just work normally. Memory persists across sessions on its own.
+  3. Optional check: ask "What do you remember about this project?"
 `);
     rl.close();
 }