memoryai-mcp 2.3.5 → 2.4.1

package/README.md

@@ -1,362 +1,362 @@
-# memoryai-mcp
-
-MCP server for [MemoryAI](https://memoryai.dev) — a living brain for your AI agent.
-
-Your AI agent gets persistent memory that works like a real brain:
-- Remembers what matters, forgets what doesn't
-- Strengthens memories you use often (Hebbian learning)
-- Consolidates knowledge while idle (Sleep cycles)
-- Protects core identity (DNA memories never fade)
-- Adapts to your emotional state
-
-**Install once. Everything auto from there.**
-
-Automation level by platform:
-- **Mechanism-level (hands-off, guaranteed):** OpenAI Proxy, Kiro (Agent Hooks), Claude Code (HTTP hooks via `memoryai-claude-setup`).
-- **Soft (rules-file, depends on the model following instructions):** Cursor, Windsurf, VS Code Copilot. MCP tools are available; add the rules file shown below.
-
-## Quick Start (2 minutes)
-
-### 1. Run setup — that's it
-
-You don't need to provision a key first. The setup command auto-provisions a
-free key for you if you don't pass one:
-
-```bash
-# Claude Code
-npx -y -p memoryai-mcp memoryai-claude-setup
-
-# Kiro
-npx -y -p memoryai-mcp memoryai-kiro-setup
-```
-
-Already have a key? Pass it to skip provisioning: `HM_API_KEY=hm_sk_... npx -y -p memoryai-mcp memoryai-claude-setup`.
-
-<details>
-<summary>Manual key provisioning (optional)</summary>
-
-```bash
-curl -X POST https://memoryai.dev/v1/admin/provision \
-  -H "Content-Type: application/json" \
-  -d '{"name": "my-agent", "tos_accepted": true}'
-```
-
-Save the `api_key` from the response.
-
-</details>
-
-### 2. Other tools (MCP config)
-
-For tools without a one-command installer, choose your platform below. Config once — memory works automatically forever.
-
----
-
-## IDE Setup
-
-### Claude Code (CLI) — one command, fully automatic
-
-```bash
-HM_API_KEY=hm_sk_your_key_here npx -y -p memoryai-mcp memoryai-claude-setup
-```
-
-This wires three HTTP hooks into `~/.claude/settings.json` plus the MCP server.
-Claude Code injects each hook's context directly into the model — **memory then
-works at the mechanism level, no agent cooperation required**:
-
-- **SessionStart** → loads DNA + recent context when a session opens
-- **UserPromptSubmit** → recalls relevant memory before each prompt
-- **Stop** → stores decisions/preferences automatically when a turn ends
-
-Re-running is safe (idempotent merge). For a project-only install set
-`MEMORYAI_SCOPE=project`. After setup, restart Claude Code and just work — you
-never call a memory tool by hand.
-
-<details>
-<summary>Manual setup (MCP only, soft automation via CLAUDE.md)</summary>
-
-If you prefer not to use hooks, add the MCP server to `~/.claude/settings.json`:
-
-```json
-{
-  "mcpServers": {
-    "memoryai": {
-      "command": "npx",
-      "args": ["-y", "memoryai-mcp"],
-      "env": {
-        "HM_ENDPOINT": "https://memoryai.dev",
-        "HM_API_KEY": "hm_sk_your_key_here"
-      }
-    }
-  }
-}
-```
-
-Then create `~/.claude/CLAUDE.md`:
-
-```markdown
-## Memory Protocol
-At the start of every conversation, call `memory_bootstrap` to load context from MemoryAI.
-Before context gets large (>100K tokens), call `memory_compact` to save important context.
-Use `memory_store` to save important decisions, preferences, and facts.
-Use `memory_recall` to search past memories when relevant.
-```
-
-Note: without hooks, memory depends on the model following CLAUDE.md (soft
-automation). The hook setup above is the guaranteed, mechanism-level path.
-
-</details>
-
-### Kiro — one command, fully automatic
-
-```bash
-HM_API_KEY=hm_sk_your_key_here npx -y -p memoryai-mcp memoryai-kiro-setup
-```
-
-Writes `.kiro/settings/mcp.json` (with autoApprove), `.kiro/steering/memoryai.md`,
-and two Agent Hooks (`promptSubmit` → recall, `agentStop` → store/compact) so
-memory is automatic at the event level.
-
-### Cursor — `~/.cursor/mcp.json`
-
-```json
-{
-  "mcpServers": {
-    "memoryai": {
-      "command": "npx",
-      "args": ["-y", "memoryai-mcp"],
-      "env": {
-        "HM_ENDPOINT": "https://memoryai.dev",
-        "HM_API_KEY": "hm_sk_your_key_here"
-      }
-    }
-  }
-}
-```
-
-Auto-bootstrap — create `.cursor/rules/memoryai.mdc`:
-
-```
-At the start of every session, call memory_bootstrap to load context.
-After completing tasks, call memory_compact to save context.
-Store important decisions and preferences with memory_store.
-```
-
-### VS Code — `.vscode/mcp.json`
-
-```json
-{
-  "servers": {
-    "memoryai": {
-      "command": "npx",
-      "args": ["-y", "memoryai-mcp"],
-      "env": {
-        "HM_ENDPOINT": "https://memoryai.dev",
-        "HM_API_KEY": "hm_sk_your_key_here"
-      }
-    }
-  }
-}
-```
-
-### Kiro — `.kiro/settings/mcp.json`
-
-```json
-{
-  "mcpServers": {
-    "memoryai": {
-      "command": "npx",
-      "args": ["-y", "memoryai-mcp"],
-      "env": {
-        "HM_ENDPOINT": "https://memoryai.dev",
-        "HM_API_KEY": "hm_sk_your_key_here"
-      }
-    }
-  }
-}
-```
-
-### Windsurf — `~/.codeium/windsurf/mcp_config.json`
-
-```json
-{
-  "mcpServers": {
-    "memoryai": {
-      "command": "npx",
-      "args": ["-y", "memoryai-mcp"],
-      "env": {
-        "HM_ENDPOINT": "https://memoryai.dev",
-        "HM_API_KEY": "hm_sk_your_key_here"
-      }
-    }
-  }
-}
-```
-
-### Claude Desktop — `claude_desktop_config.json`
-
-macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
-Windows: `%APPDATA%\Claude\claude_desktop_config.json`
-
-```json
-{
-  "mcpServers": {
-    "memoryai": {
-      "command": "npx",
-      "args": ["-y", "memoryai-mcp"],
-      "env": {
-        "HM_ENDPOINT": "https://memoryai.dev",
-        "HM_API_KEY": "hm_sk_your_key_here"
-      }
-    }
-  }
-}
-```
-
-### Antigravity — `~/.antigravity/mcp.json`
-
-```json
-{
-  "mcpServers": {
-    "memoryai": {
-      "command": "npx",
-      "args": ["-y", "memoryai-mcp"],
-      "env": {
-        "HM_ENDPOINT": "https://memoryai.dev",
-        "HM_API_KEY": "hm_sk_your_key_here"
-      }
-    }
-  }
-}
-```
-
-### Any MCP-compatible tool
-
-```json
-{
-  "mcpServers": {
-    "memoryai": {
-      "command": "npx",
-      "args": ["-y", "memoryai-mcp"],
-      "env": {
-        "HM_ENDPOINT": "https://memoryai.dev",
-        "HM_API_KEY": "hm_sk_your_key_here"
-      }
-    }
-  }
-}
-```
-
----
-
-## Auto-Bootstrap (Make It Fully Automatic)
-
-After MCP config, add a system rule so your agent auto-loads memory every session:
-
-| Platform | Rule File | Content |
-|----------|-----------|---------|
-| Claude Code | `~/.claude/CLAUDE.md` | See above |
-| Cursor | `.cursor/rules/memoryai.mdc` | See above |
-| Kiro | `.kiro/rules/memoryai.md` | Same content |
-| Windsurf | `.windsurfrules` | Same content |
-| VS Code | `.github/copilot-instructions.md` | Same content |
-
-Rule content (copy-paste for any platform):
-
-```
-## Memory Protocol
-At the start of every conversation, call `memory_bootstrap` to load context from MemoryAI.
-Before context gets large, call `memory_compact` to save important context.
-Use `memory_store` to save important decisions, preferences, and facts.
-Use `memory_recall` to search past memories when relevant.
-```
-
----
-
-## How It Works
-
-```
-Open IDE → MCP auto-connects → Agent reads rules → Calls bootstrap
-    → Loads your identity, preferences, recent work
-    → Works normally (auto-stores important stuff)
-    → Context getting full? Auto-compacts
-    → Close IDE → Sleep workers consolidate overnight
-    → Open IDE next day → Bootstrap loads everything back
-    → Cycle repeats. Memory grows smarter over time.
-```
-
-**You do nothing.** The agent handles everything automatically.
-
----
-
-## Tools Available
-
-| Tool | What It Does |
-|------|-------------|
-| `memory_bootstrap` | Wake up with full context (identity + recent + preferences) |
-| `memory_store` | Save a memory (fact, decision, preference, identity) |
-| `memory_recall` | Search memories by meaning (semantic + graph + FTS) |
-| `memory_compact` | Save conversation context before it's lost |
-| `memory_recover` | Recover session after a break |
-| `memory_health` | Check context pressure (safe/warning/critical) |
-| `memory_explore` | Explore connections between memories |
-| `memory_clusters` | View topic clusters in your knowledge graph |
-| `learn` | Store action + result + lesson learned |
-| `entity_list` | List tracked entities (files, people, packages) |
-| `reasoning_store` | Deep reasoning memory (Pro+) |
-| `reasoning_recall` | Recall reasoned insights (Pro+) |
-| `snapshot_create` | Backup memory state |
-| `snapshot_restore` | Restore from backup |
-
----
-
-## Context Guard (Built-in)
-
-Context Guard monitors your session and prevents context loss:
-
-| State | Meaning | Agent Action |
-|-------|---------|-------------|
-| SAFE | Context < 40% full | Continue normally |
-| COMPACT_SOON | Context 40-55% full | Prepare to compact |
-| COMPACT_NOW | Context > 55% full | Must compact immediately |
-
-The agent handles this automatically when rules are configured. No manual intervention needed.
-
----
-
-## What Gets Remembered (DNA System)
-
-| Memory Type | Example | Persistence |
-|-------------|---------|-------------|
-| `preference` | "I prefer Python over Java" | **Forever** (DNA-protected) |
-| `decision` | "Chose PostgreSQL for this project" | **Forever** (DNA-protected) |
-| `identity` | "Senior backend engineer, 10 years" | **Forever** (DNA-protected) |
-| `fact` | "API endpoint is /v1/users" | Decays if unused |
-| `goal` | "Launch v2.0 by June" | Decays if unused |
-
-DNA memories (preference/decision/identity) **never decay, never get deleted, never get overwritten** by any background process. They define who you are.
-
----
-
-## Pricing
-
-| Plan | Features | Price |
-|------|----------|-------|
-| Free | Basic store/recall, 100 memories | Free |
-| Pro | Full brain (reasoning, consolidation, personality) | Paid |
-| ProMax | Multi-agent mesh, advanced features | Paid |
-| God | Everything + deep graph traversal | Internal |
-
-Get started free: https://memoryai.dev
-
----
-
-## Links
-
-- Website: https://memoryai.dev
-- Python SDK: `pip install hmc-memory`
-- npm MCP: `npx memoryai-mcp`
-- GitHub: https://github.com/memoryai-dev/memoryai
-
-## License
-
-MIT
+# memoryai-mcp
+
+MCP server for [MemoryAI](https://memoryai.dev) — a living brain for your AI agent.
+
+Your AI agent gets persistent memory that works like a real brain:
+- Remembers what matters, forgets what doesn't
+- Strengthens memories you use often (Hebbian learning)
+- Consolidates knowledge while idle (Sleep cycles)
+- Protects core identity (DNA memories never fade)
+- Adapts to your emotional state
+
+**Install once. Everything auto from there.**
+
+Automation level by platform:
+- **Mechanism-level (hands-off, guaranteed):** OpenAI Proxy, Kiro (Agent Hooks), Claude Code (HTTP hooks via `memoryai-claude-setup`).
+- **Soft (rules-file, depends on the model following instructions):** Cursor, Windsurf, VS Code Copilot. MCP tools are available; add the rules file shown below.
+
+## Quick Start (2 minutes)
+
+### 1. Run setup — that's it
+
+You don't need to provision a key first. The setup command auto-provisions a
+free key for you if you don't pass one:
+
+```bash
+# Claude Code
+npx -y -p memoryai-mcp memoryai-claude-setup
+
+# Kiro
+npx -y -p memoryai-mcp memoryai-kiro-setup
+```
+
+Already have a key? Pass it to skip provisioning: `HM_API_KEY=hm_sk_... npx -y -p memoryai-mcp memoryai-claude-setup`.
+
+<details>
+<summary>Manual key provisioning (optional)</summary>
+
+```bash
+curl -X POST https://memoryai.dev/v1/admin/provision \
+  -H "Content-Type: application/json" \
+  -d '{"name": "my-agent", "tos_accepted": true}'
+```
+
+Save the `api_key` from the response.
+
+</details>
+
+### 2. Other tools (MCP config)
+
+For tools without a one-command installer, choose your platform below. Config once — memory works automatically forever.
+
+---
+
+## IDE Setup
+
+### Claude Code (CLI) — one command, fully automatic
+
+```bash
+HM_API_KEY=hm_sk_your_key_here npx -y -p memoryai-mcp memoryai-claude-setup
+```
+
+This wires three HTTP hooks into `~/.claude/settings.json` plus the MCP server.
+Claude Code injects each hook's context directly into the model — **memory then
+works at the mechanism level, no agent cooperation required**:
+
+- **SessionStart** → loads DNA + recent context when a session opens
+- **UserPromptSubmit** → recalls relevant memory before each prompt
+- **Stop** → stores decisions/preferences automatically when a turn ends
+
+Re-running is safe (idempotent merge). For a project-only install set
+`MEMORYAI_SCOPE=project`. After setup, restart Claude Code and just work — you
+never call a memory tool by hand.
+
+<details>
+<summary>Manual setup (MCP only, soft automation via CLAUDE.md)</summary>
+
+If you prefer not to use hooks, add the MCP server to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "memoryai": {
+      "command": "npx",
+      "args": ["-y", "memoryai-mcp"],
+      "env": {
+        "HM_ENDPOINT": "https://memoryai.dev",
+        "HM_API_KEY": "hm_sk_your_key_here"
+      }
+    }
+  }
+}
+```
+
+Then create `~/.claude/CLAUDE.md`:
+
+```markdown
+## Memory Protocol
+At the start of every conversation, call `memory_bootstrap` to load context from MemoryAI.
+Before context gets large (>100K tokens), call `memory_compact` to save important context.
+Use `memory_store` to save important decisions, preferences, and facts.
+Use `memory_recall` to search past memories when relevant.
+```
+
+Note: without hooks, memory depends on the model following CLAUDE.md (soft
+automation). The hook setup above is the guaranteed, mechanism-level path.
+
+</details>
+
+### Kiro — one command, fully automatic
+
+```bash
+HM_API_KEY=hm_sk_your_key_here npx -y -p memoryai-mcp memoryai-kiro-setup
+```
+
+Writes `.kiro/settings/mcp.json` (with autoApprove), `.kiro/steering/memoryai.md`,
+and two Agent Hooks (`promptSubmit` → recall, `agentStop` → store/compact) so
+memory is automatic at the event level.
+
+### Cursor — `~/.cursor/mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "memoryai": {
+      "command": "npx",
+      "args": ["-y", "memoryai-mcp"],
+      "env": {
+        "HM_ENDPOINT": "https://memoryai.dev",
+        "HM_API_KEY": "hm_sk_your_key_here"
+      }
+    }
+  }
+}
+```
+
+Auto-bootstrap — create `.cursor/rules/memoryai.mdc`:
+
+```
+At the start of every session, call memory_bootstrap to load context.
+After completing tasks, call memory_compact to save context.
+Store important decisions and preferences with memory_store.
+```
+
+### VS Code — `.vscode/mcp.json`
+
+```json
+{
+  "servers": {
+    "memoryai": {
+      "command": "npx",
+      "args": ["-y", "memoryai-mcp"],
+      "env": {
+        "HM_ENDPOINT": "https://memoryai.dev",
+        "HM_API_KEY": "hm_sk_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Kiro — `.kiro/settings/mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "memoryai": {
+      "command": "npx",
+      "args": ["-y", "memoryai-mcp"],
+      "env": {
+        "HM_ENDPOINT": "https://memoryai.dev",
+        "HM_API_KEY": "hm_sk_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Windsurf — `~/.codeium/windsurf/mcp_config.json`
+
+```json
+{
+  "mcpServers": {
+    "memoryai": {
+      "command": "npx",
+      "args": ["-y", "memoryai-mcp"],
+      "env": {
+        "HM_ENDPOINT": "https://memoryai.dev",
+        "HM_API_KEY": "hm_sk_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop — `claude_desktop_config.json`
+
+macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "memoryai": {
+      "command": "npx",
+      "args": ["-y", "memoryai-mcp"],
+      "env": {
+        "HM_ENDPOINT": "https://memoryai.dev",
+        "HM_API_KEY": "hm_sk_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Antigravity — `~/.antigravity/mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "memoryai": {
+      "command": "npx",
+      "args": ["-y", "memoryai-mcp"],
+      "env": {
+        "HM_ENDPOINT": "https://memoryai.dev",
+        "HM_API_KEY": "hm_sk_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Any MCP-compatible tool
+
+```json
+{
+  "mcpServers": {
+    "memoryai": {
+      "command": "npx",
+      "args": ["-y", "memoryai-mcp"],
+      "env": {
+        "HM_ENDPOINT": "https://memoryai.dev",
+        "HM_API_KEY": "hm_sk_your_key_here"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Auto-Bootstrap (Make It Fully Automatic)
+
+After MCP config, add a system rule so your agent auto-loads memory every session:
+
+| Platform | Rule File | Content |
+|----------|-----------|---------|
+| Claude Code | `~/.claude/CLAUDE.md` | See above |
+| Cursor | `.cursor/rules/memoryai.mdc` | See above |
+| Kiro | `.kiro/rules/memoryai.md` | Same content |
+| Windsurf | `.windsurfrules` | Same content |
+| VS Code | `.github/copilot-instructions.md` | Same content |
+
+Rule content (copy-paste for any platform):
+
+```
+## Memory Protocol
+At the start of every conversation, call `memory_bootstrap` to load context from MemoryAI.
+Before context gets large, call `memory_compact` to save important context.
+Use `memory_store` to save important decisions, preferences, and facts.
+Use `memory_recall` to search past memories when relevant.
+```
+
+---
+
+## How It Works
+
+```
+Open IDE → MCP auto-connects → Agent reads rules → Calls bootstrap
+    → Loads your identity, preferences, recent work
+    → Works normally (auto-stores important stuff)
+    → Context getting full? Auto-compacts
+    → Close IDE → Sleep workers consolidate overnight
+    → Open IDE next day → Bootstrap loads everything back
+    → Cycle repeats. Memory grows smarter over time.
+```
+
+**You do nothing.** The agent handles everything automatically.
+
+---
+
+## Tools Available
+
+| Tool | What It Does |
+|------|-------------|
+| `memory_bootstrap` | Wake up with full context (identity + recent + preferences) |
+| `memory_store` | Save a memory (fact, decision, preference, identity) |
+| `memory_recall` | Search memories by meaning (semantic + graph + FTS) |
+| `memory_compact` | Save conversation context before it's lost |
+| `memory_recover` | Recover session after a break |
+| `memory_health` | Check context pressure (safe/warning/critical) |
+| `memory_explore` | Explore connections between memories |
+| `memory_clusters` | View topic clusters in your knowledge graph |
+| `learn` | Store action + result + lesson learned |
+| `entity_list` | List tracked entities (files, people, packages) |
+| `reasoning_store` | Deep reasoning memory (Pro+) |
+| `reasoning_recall` | Recall reasoned insights (Pro+) |
+| `snapshot_create` | Backup memory state |
+| `snapshot_restore` | Restore from backup |
+
+---
+
+## Context Guard (Built-in)
+
+Context Guard monitors your session and prevents context loss:
+
+| State | Meaning | Agent Action |
+|-------|---------|-------------|
+| SAFE | Context < 40% full | Continue normally |
+| COMPACT_SOON | Context 40-55% full | Prepare to compact |
+| COMPACT_NOW | Context > 55% full | Must compact immediately |
+
+The agent handles this automatically when rules are configured. No manual intervention needed.
+
+---
+
+## What Gets Remembered (DNA System)
+
+| Memory Type | Example | Persistence |
+|-------------|---------|-------------|
+| `preference` | "I prefer Python over Java" | **Forever** (DNA-protected) |
+| `decision` | "Chose PostgreSQL for this project" | **Forever** (DNA-protected) |
+| `identity` | "Senior backend engineer, 10 years" | **Forever** (DNA-protected) |
+| `fact` | "API endpoint is /v1/users" | Decays if unused |
+| `goal` | "Launch v2.0 by June" | Decays if unused |
+
+DNA memories (preference/decision/identity) **never decay, never get deleted, never get overwritten** by any background process. They define who you are.
+
+---
+
+## Pricing
+
+| Plan | Features | Price |
+|------|----------|-------|
+| Free | Basic store/recall, 100 memories | Free |
+| Pro | Full brain (reasoning, consolidation, personality) | Paid |
+| ProMax | Multi-agent mesh, advanced features | Paid |
+| God | Everything + deep graph traversal | Internal |
+
+Get started free: https://memoryai.dev
+
+---
+
+## Links
+
+- Website: https://memoryai.dev
+- Python SDK: `pip install hmc-memory`
+- npm MCP: `npx memoryai-mcp`
+- GitHub: https://github.com/memoryai-dev/memoryai
+
+## License
+
+MIT

package/dist/claude-setup.js

@@ -69,19 +69,19 @@ function ensureHook(settings, event, handler) {
     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 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",
@@ -199,14 +199,14 @@ async function main() {
     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.
+    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();
 }

package/dist/index.js

@@ -11,6 +11,7 @@ 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
+const MCP_VERSION = "2.4.1";
 // 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
@@ -55,6 +56,7 @@ async function api(method, path, body) {
         headers: {
             Authorization: `Bearer ${API_KEY}`,
             "Content-Type": "application/json",
+            "User-Agent": `memoryai-mcp/${MCP_VERSION}`,
         },
         body: body ? JSON.stringify(body) : undefined,
         signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
@@ -150,10 +152,70 @@ function err(e) {
     return { content, isError: true };
 }
 // --- MCP Server ---
-const server = new McpServer({ name: "memoryai", version: "2.3.1" }, {
+const server = new McpServer({ name: "memoryai", version: "2.4.1" }, {
     capabilities: { tools: {} },
     instructions: "MemoryAI persistent memory. Call memory_bootstrap on session start. After decisions/preferences, call memory_store. Context compaction is automatic via piggybacking — follow any [Context Guard] directives in tool responses.",
 });
+// ─── Tool tier filter ────────────────────────────────────────────────────────
+// Public surface stays minimal. Internal/architectural tools (L2 banks, brain
+// thinking, federation, inheritance, trust graph, twin, benchmark, spec) are
+// hidden by default and only registered when MEMORYAI_TIER=admin (dogfood).
+//
+// Tiers:
+//   core (default) — minimum useful set: store/recall/bootstrap + context guard.
+//   pro            — adds plan/goal/handoff/health/pitfall productivity tools.
+//   admin          — every tool (dogfood / internal). DO NOT enable on user installs.
+//
+// Override per-deployment via MEMORYAI_TIER env var.
+const TIER = (process.env.MEMORYAI_TIER || "core").toLowerCase();
+const TOOLS_CORE = new Set([
+    // The honest minimum — what users actually use day-to-day.
+    "memory_store",
+    "memory_recall",
+    "memory_bootstrap",
+    "memory_stats",
+    "context_guard_check",
+    "context_guard_compact",
+    "ide_turn_check",
+    // Bot interface — pure protocol, no architecture leak.
+    "bot_session_message",
+    "bot_guard_check",
+    "bot_guard_bootstrap",
+]);
+const TOOLS_PRO = new Set([
+    ...TOOLS_CORE,
+    // Productivity wrappers — names describe behaviour, not architecture.
+    "memory_compact",
+    "memory_recover",
+    "memory_health",
+    "memory_pitfall_check",
+    "memory_plan_save",
+    "memory_plan_resume",
+    "memory_goal_track",
+    "memory_changelog",
+    "session_handoff_start",
+    "session_handoff_restore",
+    "session_handoff_complete",
+    "session_handoff_status",
+    "context_check",
+    "context_restore",
+    "context_guard_bootstrap",
+]);
+function _shouldRegisterTool(name) {
+    if (TIER === "admin")
+        return true;
+    if (TIER === "pro")
+        return TOOLS_PRO.has(name);
+    return TOOLS_CORE.has(name);
+}
+// Wrap server.tool so any registration outside the configured tier becomes a
+// silent no-op. Existing call sites stay untouched.
+const _origTool = server.tool.bind(server);
+server.tool = (name, ...rest) => {
+    if (!_shouldRegisterTool(name))
+        return undefined;
+    return _origTool(name, ...rest);
+};
 // 1. memory_store
 server.tool("memory_store", "[CORE] Store information in persistent memory. Use when you learn something important — project context, user preferences, architectural decisions, patterns, bugs, pricing/cost discussions, business plans, or ANY information the user might ask about later. When in doubt, STORE — dedup is automatic.", {
     content: z.string().describe("What to remember"),

package/dist/kiro-setup.js

@@ -92,41 +92,41 @@ const MCP_CONFIG = (apiKey, endpoint) => JSON.stringify({
         },
     },
 }, null, 2) + "\n";
-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.
+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.
@@ -180,15 +180,15 @@ async function main() {
     writeIfMissing(join(cwd, ".kiro", "steering", "memoryai.md"), STEERING, ".kiro/steering/memoryai.md");
     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?"
+    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();
 }

package/package.json

@@ -1,46 +1,46 @@
-{
-  "name": "memoryai-mcp",
-  "version": "2.3.5",
-  "description": "MCP server for MemoryAI v2.3 — One brain. ∞ agents. Forever. Adds Brain Inheritance/Federation (P2.3), L2 Inject endpoint (DNA #2 retina), Protocol v1 spec lookup. Plus the v2.0 base: Brain Export/Import, Public Benchmark, Trust Graph, Cognitive Twin. Plus the v1.5 base: 11 biological behaviors, DNA-protected memories, Multi-Agent Mesh.",
-  "homepage": "https://memoryai.dev",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/memoryai-dev/memoryai"
-  },
-  "type": "module",
-  "main": "dist/index.js",
-  "bin": {
-    "memoryai-mcp": "dist/index.js",
-    "memoryai-kiro-setup": "dist/kiro-setup.js",
-    "memoryai-claude-setup": "dist/claude-setup.js"
-  },
-  "scripts": {
-    "build": "tsc",
-    "start": "node dist/index.js",
-    "dev": "tsx src/index.ts"
-  },
-  "keywords": [
-    "mcp",
-    "memory",
-    "ai",
-    "llm",
-    "context"
-  ],
-  "license": "MIT",
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.19.15",
-    "tsx": "^4.0.0",
-    "typescript": "^5.5.0"
-  }
-}
+{
+  "name": "memoryai-mcp",
+  "version": "2.4.1",
+  "description": "MCP server for MemoryAI v2.3 — One brain. Every AI you use. Forever. Persistent memory and context guard tools for IDEs and bots.",
+  "homepage": "https://memoryai.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/memoryai-dev/memoryai"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "memoryai-mcp": "dist/index.js",
+    "memoryai-kiro-setup": "dist/kiro-setup.js",
+    "memoryai-claude-setup": "dist/claude-setup.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts"
+  },
+  "keywords": [
+    "mcp",
+    "memory",
+    "ai",
+    "llm",
+    "context"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.15",
+    "tsx": "^4.0.0",
+    "typescript": "^5.5.0"
+  }
+}