memoryai-mcp 0.9.0 → 2.1.0

package/README.md

@@ -1,31 +1,37 @@
 # memoryai-mcp
 
-MCP server for [MemoryAI](https://memoryai.dev) — a brain for your AI agent.
+MCP server for [MemoryAI](https://memoryai.dev) — a living brain for your AI agent.
 
-Gives your IDE agent long-term memory that persists across sessions. Memories are processed through 4 stages, just like the human brain:
+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
 
-- ⚡ **Instant Recall** — What's on the tip of your tongue. Always ready.
-- 🔍 **Deep Search** — Scans memory by meaning, not just keywords.
-- 🧠 **Reasoning** — Connects the dots across memories, synthesizes precise answers. *(Pro)*
-- 📦 **Archive** — Compressed long-term storage. Nothing truly forgotten.
+**Install once. Everything auto from there.**
 
-The more you recall a memory, the stronger it gets. Unused ones gently age — but can always be recovered.
+## Quick Start (2 minutes)
 
-## Install
+### 1. Get an API Key
 
 ```bash
-npx memoryai-mcp
+curl -X POST https://memoryai.dev/v1/admin/provision \
+  -H "Content-Type: application/json" \
+  -d '{"name": "my-agent", "tos_accepted": true}'
 ```
 
-Or install globally:
+Save the `api_key` from the response. You'll need it below.
 
-```bash
-npm install -g memoryai-mcp
-```
+### 2. Pick Your IDE/Tool
+
+Choose your platform below. Config once — memory works automatically forever.
+
+---
 
 ## IDE Setup
 
-### Cursor (`~/.cursor/mcp.json`)
+### Claude Code (CLI) — `~/.claude/settings.json`
 
 ```json
 {
@@ -42,7 +48,42 @@ npm install -g memoryai-mcp
 }
 ```
 
-### VS Code (`.vscode/mcp.json`)
+Then create `~/.claude/CLAUDE.md` for auto-bootstrap:
+
+```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.
+```
+
+### 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
 {
@@ -59,7 +100,7 @@ npm install -g memoryai-mcp
 }
 ```
 
-### Claude Desktop (`claude_desktop_config.json`)
+### Kiro — `.kiro/settings/mcp.json`
 
 ```json
 {
@@ -76,7 +117,7 @@ npm install -g memoryai-mcp
 }
 ```
 
-### Windsurf (`~/.codeium/windsurf/mcp_config.json`)
+### Windsurf — `~/.codeium/windsurf/mcp_config.json`
 
 ```json
 {
@@ -93,7 +134,10 @@ npm install -g memoryai-mcp
 }
 ```
 
-### Kiro (`.kiro/settings/mcp.json`)
+### Claude Desktop — `claude_desktop_config.json`
+
+macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+Windows: `%APPDATA%\Claude\claude_desktop_config.json`
 
 ```json
 {
@@ -110,60 +154,149 @@ npm install -g memoryai-mcp
 }
 ```
 
-### OpenClaw (`openclaw.yaml`)
+### Antigravity — `~/.antigravity/mcp.json`
 
-```yaml
-mcp:
-  servers:
-    memoryai:
-      command: npx
-      args: ["-y", "memoryai-mcp"]
-      env:
-        HM_ENDPOINT: "https://memoryai.dev"
-        HM_API_KEY: "hm_sk_..."
+```json
+{
+  "mcpServers": {
+    "memoryai": {
+      "command": "npx",
+      "args": ["-y", "memoryai-mcp"],
+      "env": {
+        "HM_ENDPOINT": "https://memoryai.dev",
+        "HM_API_KEY": "hm_sk_your_key_here"
+      }
+    }
+  }
+}
 ```
 
-## Tools
+### Any MCP-compatible tool
 
-| Tool | Description |
-|------|-------------|
-| `memory_bootstrap` | Load context at session start — wake up with full memory |
-| `memory_store` | Store information in persistent memory |
-| `memory_recall` | Search memories by semantic query |
-| `memory_compact` | Consolidate context into key memories (like brain during sleep) |
-| `memory_recover` | Recover session context after a break |
-| `memory_health` | Check how full your working memory is |
-| `memory_explore` | Explore connections between memories |
-| `memory_clusters` | View topic clusters |
-| `learn` | Store action + result + lesson |
-| `entity_list` | List tracked entities (files, people, packages) |
-| `reasoning_store/recall` | Deep reasoning memory (Pro+) |
-| `snapshot_create/restore` | Backup and restore memory state |
+```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)
 
-## Auto-Bootstrap
+After MCP config, add a system rule so your agent auto-loads memory every session:
 
-Add to your project rules so the agent auto-loads memory each 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):
 
-**Cursor** (`.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.
+## 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.
 ```
 
-## Get an API Key
+---
 
-```bash
-curl -X POST https://memoryai.dev/v1/admin/provision \
-  -H "Content-Type: application/json" \
-  -d '{"name": "my-agent", "tos_accepted": true}'
+## 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.
 ```
 
-Or visit https://memoryai.dev to create one instantly.
+**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: https://pypi.org/project/hmc-memory/
+- Python SDK: `pip install hmc-memory`
+- npm MCP: `npx memoryai-mcp`
 - GitHub: https://github.com/memoryai-dev/memoryai
 
 ## License

package/dist/index.js

@@ -11,6 +11,10 @@ import { z } from "zod";
 const API_URL = process.env.HM_ENDPOINT || "http://localhost:8420";
 const 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
+const CG_CONTEXT_CAP = parseInt(process.env.HM_CONTEXT_CAP || "0", 10); // IDE's context window (0 = let server detect)
+const CG_COMPACT_PCT = parseInt(process.env.HM_COMPACT_AT || "0", 10); // % to warn (e.g. 30 = 30%)
+const CG_CRITICAL_PCT = parseInt(process.env.HM_CRITICAL_AT || "0", 10); // % to force compact (e.g. 50 = 50%)
 // --- HTTP helper ---
 async function api(method, path, body) {
     const resp = await fetch(`${API_URL}${path}`, {
@@ -36,19 +40,21 @@ function err(e) {
     return { content: [{ type: "text", text: `Error: ${msg}` }], isError: true };
 }
 // --- MCP Server ---
-const server = new McpServer({ name: "memoryai", version: "0.5.0" }, { capabilities: { tools: {} } });
+const server = new McpServer({ name: "memoryai", version: "0.9.0" }, { capabilities: { tools: {} } });
 // 1. memory_store
-server.tool("memory_store", "Store information in persistent memory. Use when you learn something important — project context, user preferences, architectural decisions, patterns, or bugs.", {
+server.tool("memory_store", "Store information in persistent memory. Use when you learn something important — project context, user preferences, architectural decisions, patterns, bugs, pricing/cost discussions, business plans, financial calculations, credit/billing info, revenue models, partnership details, or ANY information the user might ask about later. When in doubt, STORE — MemoryAI handles dedup automatically, so storing too much is always better than forgetting.", {
     content: z.string().describe("What to remember"),
     source: z.string().optional().describe("Source context (e.g. file path, conversation)"),
     tags: z.array(z.string()).optional().describe("Categories: preferences, architecture, bugs, patterns, decisions"),
     priority: z.enum(["hot", "warm", "cold"]).optional().describe("Memory priority (default: warm)"),
-    memory_type: z.enum(["fact", "decision", "preference", "error", "goal", "episodic", "identity"]).optional().describe("Memory type. 'preference', 'decision', 'identity' are DNA-protected — never decay, 1.5x recall boost. Default: fact"),
+    memory_type: z.enum(["fact", "decision", "preference", "error", "goal", "episodic", "identity", "pitfall", "life_event", "procedure"]).optional().describe("Memory type. 'preference', 'decision', 'identity', 'procedure' are DNA-protected — never decay, 1.5x recall boost. 'pitfall' for failure memories. 'procedure' for learned workflows/steps. Default: fact"),
     retention: z.enum(["auto", "forever", "6m", "1y"]).optional().describe("Retention policy. 'forever' = never deleted. Default: auto"),
     content_type: z.enum(["conversation", "code", "decision", "preference", "architecture", "lesson_learned", "todo", "entity", "pattern", "environment", "bug_fix", "action_log"]).optional().describe("Content type — helps with filtering and recall accuracy"),
     metadata: z.record(z.string(), z.unknown()).optional().describe("Additional metadata (JSONB)"),
     zone: z.enum(["critical", "important", "standard", "ephemeral"]).optional().describe("Memory zone (default: standard). critical=never evict, ephemeral=auto-expire"),
     importance: z.number().min(0).max(1).optional().describe("Importance score 0.0-1.0 (default: 0.5). Higher = slower decay, prioritized in recall"),
+    project_id: z.string().optional().describe("Scope memory to a project/workspace. DNA memories (preference/decision/identity/pitfall) are always cross-project visible."),
+    thread_id: z.string().optional().describe("Scope memory to a conversation thread. Memories without thread_id are visible in all threads. Use for parallel topics (e.g. 'relationship', 'career')."),
 }, async (args) => {
     try {
         const r = (await api("POST", "/v1/store", {
@@ -62,6 +68,8 @@ server.tool("memory_store", "Store information in persistent memory. Use when yo
             metadata: args.metadata,
             zone: args.zone || "standard",
             importance: args.importance ?? 0.5,
+            project_id: args.project_id,
+            thread_id: args.thread_id,
         }));
         let msg = `Stored (id=${r.id}, type=${args.memory_type || "fact"})`;
         if (r.deduplicated) {
@@ -81,12 +89,14 @@ server.tool("memory_store", "Store information in persistent memory. Use when yo
 // 2. memory_recall
 server.tool("memory_recall", "Search persistent memory for relevant context. Use before starting work to check what you already know about the project or task.", {
     query: z.string().describe("What to search for"),
-    depth: z.enum(["fast", "deep", "exhaustive"]).optional().describe("Search depth (default: deep)"),
+    depth: z.enum(["fast", "instant", "deep", "exhaustive"]).optional().describe("Search depth. 'instant'=vector only (~50ms), 'fast'=FTS only, 'deep'=full fusion (default), 'exhaustive'=deep+more results"),
     limit: z.number().optional().describe("Max results (default: 5)"),
     min_score: z.number().optional().describe("Minimum relevance score 0-1 (default: 0)"),
     tags: z.array(z.string()).optional().describe("Filter by tags"),
     max_tokens: z.number().optional().describe("Token budget limit — results truncated to fit within this budget"),
     priority_min: z.enum(["critical", "important", "standard", "ephemeral"]).optional().describe("Minimum zone priority filter (default: all zones)"),
+    project_id: z.string().optional().describe("Scope recall to a project/workspace. DNA memories are always visible cross-project."),
+    thread_id: z.string().optional().describe("Scope recall to a conversation thread. Memories without thread_id are always visible."),
 }, async (args) => {
     try {
         const body = {
@@ -100,6 +110,10 @@ server.tool("memory_recall", "Search persistent memory for relevant context. Use
             body.max_tokens = args.max_tokens;
         if (args.priority_min)
             body.priority_min = args.priority_min;
+        if (args.project_id)
+            body.project_id = args.project_id;
+        if (args.thread_id)
+            body.thread_id = args.thread_id;
         const r = (await api("POST", "/v1/recall", body));
         if (!r.results?.length)
             return ok("No relevant memories found.");
@@ -800,6 +814,481 @@ server.tool("session_handoff_status", "Check current session handoff status —
         return err(e);
     }
 });
+// ─── Context Guard v6 Tools ─────────────────────────────────────────
+// context_guard_check — universal guard check with DNA count
+server.tool("context_guard_check", "Check context window health using Context Guard v6 — dynamic thresholds, DNA memory count, bootstrap readiness. Replaces memory_health with richer data.", {
+    estimated_tokens: z.number().describe("Current token count in context window"),
+    max_tokens: z.number().optional().describe("Max context window size (uses HM_CONTEXT_CAP env if omitted)"),
+    model: z.string().optional().describe("Model name for auto-detecting context window size (e.g. claude-sonnet-4-6)"),
+}, async (args) => {
+    try {
+        // Use env var HM_CONTEXT_CAP as default if max_tokens not provided
+        const maxTokens = args.max_tokens || CG_CONTEXT_CAP || 0;
+        const payload = {
+            estimated_tokens: args.estimated_tokens,
+            max_tokens: maxTokens,
+            model: args.model || null,
+        };
+        // Send per-IDE threshold overrides if configured via env vars
+        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;
+        const barLen = 20;
+        const filled = Math.round(pct / 100 * 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` +
+            `Urgency: ${r.urgency}\n` +
+            `Thresholds: compact=${r.compact_at_tokens.toLocaleString()}, 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"));
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// context_guard_compact — compact with DNA protection
+server.tool("context_guard_compact", "Compact session context with DNA protection — DNA memories are never overwritten. IMPORTANT: Send a REAL summary of the conversation (>500 chars) including topics discussed, decisions made, key numbers/facts, and current status. Do NOT send just a status string like 'context guard - 132%'. If you send useless content, the server will use its internal buffer as fallback, but a good summary from you produces better memories.", {
+    content: z.string().describe("Conversation summary — include topics, decisions, key facts, numbers. Must be >500 chars of real content."),
+    task_context: z.string().optional().describe("Task description for tagging"),
+    blocking: z.boolean().optional().describe("Wait for result (true) or return task_id (false, default)"),
+}, async (args) => {
+    try {
+        const r = (await api("POST", "/v1/context/guard/compact", {
+            content: args.content,
+            task_context: args.task_context || null,
+            blocking: args.blocking || false,
+        }));
+        if (r.status === "queued") {
+            return ok(`Compact queued (task_id=${r.task_id}). Poll with guard_status.`);
+        }
+        return ok(`Compact ${r.status}: ${r.chunks_created} chunks stored, ${r.chunks_deduplicated} deduplicated.\n` +
+            r.message);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// context_guard_bootstrap — DNA-first session bootstrap
+server.tool("context_guard_bootstrap", "Bootstrap a new session with DNA-first context — identity/preferences first, then recent activity, then task-relevant memories. For BOT clients: uses 3-tier wake-up (800 tokens). For IDE: flat layout (~4000 tokens).", {
+    task: z.string().describe("Task description for the new session"),
+    limit: z.number().optional().describe("Max memories to include (default: 10)"),
+    mode: z.enum(["default", "deep"]).optional().describe("'default' = 800 token 3-tier wake-up, 'deep' = full context with L2 chunks"),
+    token_budget: z.number().optional().describe("Token budget for bootstrap (default: 800 for bot, 4000 for IDE)"),
+}, async (args) => {
+    try {
+        const r = (await api("POST", "/v1/bot/guard/bootstrap", {
+            task: args.task,
+            limit: args.limit || 10,
+            mode: args.mode || "default",
+            token_budget: args.token_budget,
+        }));
+        return ok(`Bootstrap complete: ${r.memories_included} memories\n` +
+            `Tokens used: ${r.tokens_used}\n` +
+            `L2 sessions: ${r.l2_sessions_included || 0}\n\n` +
+            r.context_block);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// bot_session_message — Rolling 3-session tracking (60 msg raw context)
+server.tool("bot_session_message", "Track a message in the rolling session (rolling 3: keeps 60 messages raw in LLM context). Call on EVERY message (user + assistant). Returns rotate=true when session hits 20 messages. When should_compress=true, compress the oldest session via bot_session_compress.", {
+    message: z.object({
+        role: z.enum(["user", "assistant"]).describe("Message role"),
+        content: z.string().describe("Message content"),
+    }).describe("The message to track"),
+    rotation_size: z.number().optional().describe("Messages per session before rotation (default: 20, range: 5-50)"),
+}, async (args) => {
+    try {
+        const r = (await api("POST", "/v1/bot/session/message", {
+            message: args.message,
+            rotation_size: args.rotation_size || 20,
+        }));
+        if (r.rotate) {
+            let output = `🔄 SESSION ROTATED\n` +
+                `New session: ${r.session_id} (msg ${r.message_count})\n` +
+                `Context: ${r.context_message_count} messages raw in LLM\n`;
+            if (r.should_compress) {
+                output += `\n⚠️ COMPRESS: session ${r.compress_session_id} (${r.compress_message_count} msgs)\n` +
+                    `Action: Call bot_session_compress with session_id="${r.compress_session_id}"`;
+            }
+            return ok(output);
+        }
+        return ok(`Session ${r.session_id}: ${r.message_count}/20 messages | context: ${r.context_message_count} msgs`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// bot_guard_check — Bot-specific guard with spawn signal
+server.tool("bot_guard_check", "Bot context guard — checks context pressure AND returns spawn signal. When should_spawn_new_session=true, bot should spawn a new session and compress the old one later. Use this instead of context_guard_check for bot/chatbot clients.", {
+    estimated_tokens: z.number().describe("Current token count in context window"),
+    max_tokens: z.number().optional().describe("Max context window size (default: 200000)"),
+    model: z.string().optional().describe("Model name for auto-detecting context window size"),
+    compress_threshold: z.number().optional().describe("Custom spawn threshold in tokens (default: 70% of max_tokens)"),
+}, async (args) => {
+    try {
+        const payload = {
+            estimated_tokens: args.estimated_tokens,
+            max_tokens: args.max_tokens || CG_CONTEXT_CAP || 200000,
+            model: args.model || null,
+        };
+        if (args.compress_threshold)
+            payload.compress_threshold = args.compress_threshold;
+        const r = (await api("POST", "/v1/bot/guard/check", payload));
+        const pct = r.usage_percent;
+        const barLen = 20;
+        const filled = Math.round(pct / 100 * barLen);
+        const bar = "\u2588".repeat(filled) + "\u2591".repeat(barLen - filled);
+        let output = `Bot Guard:\n` +
+            `[${bar}] ${pct.toFixed(1)}%\n` +
+            `Recommendation: ${r.recommendation.toUpperCase()}${r.should_compact ? " — compact now" : ""}\n` +
+            `Urgency: ${r.urgency}\n` +
+            `Spawn threshold: ${r.compress_threshold.toLocaleString()} tokens\n` +
+            `DNA memories: ${r.dna_memories} | Bootstrap ready: ${r.bootstrap_ready ? "yes" : "no"}\n`;
+        if (r.should_spawn_new_session) {
+            output += `\n⚠️ SPAWN NEW SESSION: ${r.spawn_reason}\n`;
+            output += `Action: Start new session → when new session reaches 20K tokens → compress old session via /v1/bot/session/compress`;
+        }
+        return ok(output);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// ── Self-Thinking Tools ──────────────────────────────────────────────
+// brain_thoughts — Get current active thoughts
+server.tool("brain_thoughts", "Get the brain's current active thoughts — what it's thinking about autonomously.", {
+    limit: z.number().optional().describe("Max thoughts to return (default: 10)"),
+}, async (args) => {
+    try {
+        const r = (await api("GET", `/v1/brain/thoughts?limit=${args.limit || 10}`));
+        if (!r.thoughts || r.thoughts.length === 0)
+            return ok("Brain has no active thoughts right now.");
+        const lines = r.thoughts.map((t) => `[${t.thought_type}] ${t.content} (confidence: ${t.confidence}, urgency: ${t.urgency})`);
+        return ok(`Active thoughts (${r.count}):\n${lines.join("\n")}`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// brain_think_about — Request brain to think about a topic
+server.tool("brain_think_about", "Request the brain to think about a specific topic. The brain will deliberate on it in its next thinking cycle.", {
+    topic: z.string().describe("What should the brain think about?"),
+}, async (args) => {
+    try {
+        const r = (await api("POST", "/v1/brain/think-about", { topic: args.topic }));
+        return ok(`Queued for thinking: "${args.topic}"\nQueue size: ${r.queue_size}`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// brain_hypotheses — Get active hypotheses
+server.tool("brain_hypotheses", "Get hypotheses the brain is currently testing — predictions about user behavior patterns.", {
+    limit: z.number().optional().describe("Max hypotheses to return (default: 10)"),
+}, async (args) => {
+    try {
+        const r = (await api("GET", `/v1/brain/hypotheses?limit=${args.limit || 10}`));
+        if (!r.hypotheses || r.hypotheses.length === 0)
+            return ok("No active hypotheses being tested.");
+        const lines = r.hypotheses.map((h) => `[${h.status}] ${h.hypothesis} (confidence: ${h.confidence})`);
+        return ok(`Hypotheses (${r.count}):\n${lines.join("\n")}`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// brain_feedback — Rate a thought
+server.tool("brain_feedback", "Rate a thought as useful or not — helps the brain learn what's worth thinking about.", {
+    thought_id: z.number().describe("ID of the thought to rate"),
+    useful: z.boolean().describe("Was this thought useful?"),
+}, async (args) => {
+    try {
+        await api("POST", "/v1/brain/thoughts/feedback", {
+            thought_id: args.thought_id,
+            useful: args.useful,
+        });
+        return ok(`Feedback recorded: thought #${args.thought_id} marked as ${args.useful ? "useful" : "not useful"}`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// brain_thinking_stats — Budget and efficiency
+server.tool("brain_thinking_stats", "Get thinking system statistics — token budget, efficiency, queue size, and meta-cognition report.", {}, async () => {
+    try {
+        const r = (await api("GET", "/v1/brain/thinking-stats"));
+        return ok(`Budget: ${r.budget.remaining_tokens} tokens remaining (limit: ${r.budget.limit_per_hour}/hr)\n` +
+            `Efficiency: ${(r.budget.efficiency * 100).toFixed(1)}%\n` +
+            `Queue size: ${r.queue_size}\n` +
+            `Total thoughts: ${r.meta.total_thoughts} (${r.meta.useful_thoughts} useful)\n` +
+            `Interval: ${r.meta.recommended_interval_seconds}s\n` +
+            `Best types: ${r.meta.best_types.join(", ") || "none yet"}\n` +
+            `Suppressed: ${r.meta.suppressed_types.join(", ") || "none"}`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// ── Session Settings Tools ──────────────────────────────────────────
+// memory_auto_extract — LLM-based fact extraction from conversation
+server.tool("memory_auto_extract", "CRITICAL: Call this at the END of every conversation session to extract and store important facts automatically. Uses LLM analysis to identify pricing, decisions, plans, technical details, and anything worth remembering. This is MORE reliable than manual memory_store because it catches things you might forget to store. ALWAYS call this before the conversation ends — especially after discussions about money, pricing, plans, decisions, or business.", {
+    conversation: z.string().describe("The conversation text to extract facts from (include both user and assistant messages)"),
+    source: z.string().optional().describe("Source context (e.g. 'discord chat', 'slack thread')"),
+    store: z.boolean().optional().describe("Whether to store extracted facts (default: true). Set false to preview what would be extracted."),
+}, async (args) => {
+    try {
+        const r = (await api("POST", "/v1/memory/auto-extract", {
+            conversation: args.conversation,
+            source: args.source || "auto-extract",
+            store: args.store !== false,
+        }));
+        if (!r.facts?.length)
+            return ok("No extractable facts found in conversation.");
+        const factList = r.facts
+            .map((f, i) => `${i + 1}. [${f.memory_type || 'fact'}] ${f.content}`)
+            .join("\n");
+        return ok(`Extracted ${r.facts.length} facts (added: ${r.added}, updated: ${r.updated}, skipped: ${r.skipped}):\n\n${factList}`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// ── IDE Upgrade Tools ──────────────────────────────────────────────
+// memory_pitfall_check — Check pitfalls before risky actions
+server.tool("memory_pitfall_check", "IMPORTANT: Call this BEFORE executing risky actions (deploy, rm, git push, database changes). Returns known pitfalls (past failures + lessons) so you can avoid repeating mistakes. Pitfalls are DNA-protected and never expire.", {
+    intent: z.string().describe("What you're about to do (e.g. 'deploy to production', 'delete user table')"),
+    tags: z.array(z.string()).optional().describe("Filter by tags"),
+    limit: z.number().optional().describe("Max results (default 5)"),
+}, async (args) => {
+    try {
+        const r = (await api("POST", "/v1/bot/pitfall/check", {
+            intent: args.intent,
+            tags: args.tags,
+            limit: args.limit || 5,
+        }));
+        if (!r.has_pitfalls)
+            return ok("No known pitfalls for this action. Proceed safely.");
+        const list = r.pitfalls
+            .map((p, i) => `${i + 1}. [score: ${p.score}] ${p.content}`)
+            .join("\n");
+        return ok(`⚠️ ${r.pitfalls.length} pitfall(s) found:\n\n${list}\n\nReview before proceeding.`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// memory_plan_save — Save current plan/state for session resumption
+server.tool("memory_plan_save", "Save your current work state (plan steps, cursor position, active goals) so you can resume exactly where you left off in the next session. Call before session ends or when switching tasks.", {
+    session_id: z.string().optional().describe("Session identifier (default: 'default')"),
+    state: z.record(z.string(), z.unknown()).describe("State to save: {plan: [...], cursor: 3, active_goal: '...', last_action: '...', files_read: [...]}"),
+}, async (args) => {
+    try {
+        const r = (await api("POST", "/v1/bot/state/save", {
+            session_id: args.session_id || "default",
+            state: args.state,
+        }));
+        return ok(`State saved for session '${r.session_id}'. Will be restored on next bootstrap.`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// memory_plan_resume — Restore saved state from previous session
+server.tool("memory_plan_resume", "Restore your work state from a previous session. Returns plan steps, cursor position, active goals — everything needed to continue where you left off.", {
+    session_id: z.string().optional().describe("Session identifier (default: 'default')"),
+}, async (args) => {
+    try {
+        const r = (await api("GET", `/v1/bot/state/restore?session_id=${args.session_id || "default"}`));
+        if (r.status === "not_found")
+            return ok("No saved state found for this session. Starting fresh.");
+        return ok(`State restored (saved at ${r.saved_at}):\n\n${JSON.stringify(r.state, null, 2)}`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// memory_goal_track — Create/update/query goals
+server.tool("memory_goal_track", "Track goals across sessions. Create new goals, update progress, or query active goals. Goals with status='active' are DNA-protected (never decay).", {
+    action: z.enum(["create", "update", "list"]).describe("Action to perform"),
+    title: z.string().optional().describe("Goal title (for create)"),
+    progress: z.number().optional().describe("Progress 0.0-1.0 (for update)"),
+    goal_id: z.number().optional().describe("Goal ID (for update)"),
+    status: z.enum(["active", "achieved", "abandoned"]).optional().describe("New status (for update)"),
+}, async (args) => {
+    try {
+        if (args.action === "create") {
+            const r = (await api("POST", "/v1/store", {
+                content: args.title,
+                memory_type: "goal",
+                zone: "important",
+                tags: ["goal", "active"],
+            }));
+            return ok(`Goal created: "${args.title}" (id: ${r.id}). DNA-protected while active.`);
+        }
+        else if (args.action === "list") {
+            const r = (await api("POST", "/v1/recall", {
+                query: "active goals and objectives",
+                memory_type: "goal",
+                depth: "deep",
+                limit: 10,
+            }));
+            if (!r.results?.length)
+                return ok("No active goals found.");
+            const list = r.results.map((g, i) => `${i + 1}. ${g.content}`).join("\n");
+            return ok(`Active goals:\n\n${list}`);
+        }
+        else {
+            return ok("Goal update: use memory_store with memory_type='goal' to update goal content.");
+        }
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// memory_thought_log — Query what the brain has been thinking about
+server.tool("memory_thought_log", "See what the brain has been thinking about autonomously. Returns recent thoughts, hypotheses, and insights generated during idle time.", {
+    limit: z.number().optional().describe("Max thoughts to return (default 5)"),
+}, async (args) => {
+    try {
+        const r = (await api("GET", `/v1/brain/thoughts?limit=${args.limit || 5}`));
+        if (!r.thoughts?.length)
+            return ok("No recent thoughts. The brain thinks during idle periods.");
+        const list = r.thoughts
+            .map((t, i) => `${i + 1}. [${t.thought_type}] ${t.content} (urgency: ${t.urgency})`)
+            .join("\n");
+        return ok(`Recent brain thoughts:\n\n${list}`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// memory_feedback — Report recall quality for self-improvement
+server.tool("memory_feedback", "Report whether recall results were helpful. This feeds the neuroplasticity system — over time, the brain learns what works for YOUR specific patterns and improves recall quality.", {
+    query: z.string().describe("The recall query that was made"),
+    chunk_ids: z.array(z.number()).describe("IDs of chunks that were returned"),
+    helpful: z.boolean().describe("Were the results helpful for your task?"),
+    action_succeeded: z.boolean().optional().describe("Did the action using these memories succeed? (default: true)"),
+}, async (args) => {
+    try {
+        const r = (await api("POST", "/v1/bot/feedback", {
+            query: args.query,
+            chunk_ids: args.chunk_ids,
+            helpful: args.helpful,
+            action_succeeded: args.action_succeeded !== false,
+        }));
+        return ok(r.message || "Feedback recorded. Brain will adapt over time.");
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// memory_predict — Predictive recall (push intent, get predicted memories)
+server.tool("memory_predict", "Predictive recall — tell the brain what you're about to do and get relevant memories pre-loaded. Call this when you can anticipate what context will be needed next.", {
+    intent: z.string().describe("What you/user are about to do"),
+    context: z.string().optional().describe("Current conversation context (helps prediction accuracy)"),
+    limit: z.number().optional().describe("Max predictions (default 5)"),
+}, async (args) => {
+    try {
+        const r = (await api("POST", "/v1/bot/predict", {
+            intent: args.intent,
+            context: args.context || "",
+            limit: args.limit || 5,
+        }));
+        if (!r.predictions?.length)
+            return ok("No relevant predictions for this intent.");
+        const list = r.predictions
+            .map((p, i) => `${i + 1}. [${p.memory_type || 'memory'}] ${p.content}\n   (score: ${p.score}, reason: ${p.reason})`)
+            .join("\n\n");
+        return ok(`Predicted ${r.count} relevant memories:\n\n${list}`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// memory_changelog — What changed since last session
+server.tool("memory_changelog", "See what changed in your memory since your last session. Shows new memories, updates, invalidations, and insights from overnight consolidation. Call at session start after bootstrap to understand what the brain learned while you were away.", {
+    since: z.string().describe("ISO datetime — show changes after this time (e.g. '2026-05-20T10:00:00Z')"),
+    project_id: z.string().optional().describe("Filter to specific project"),
+    limit: z.number().optional().describe("Max changes to return (default 50)"),
+}, async (args) => {
+    try {
+        const r = (await api("POST", "/v1/memory/changelog", {
+            since: args.since,
+            project_id: args.project_id,
+            limit: args.limit || 50,
+        }));
+        if (!r.changes?.length)
+            return ok("No changes since last session. Memory is up to date.");
+        const list = r.changes
+            .map((c, i) => `${i + 1}. [${c.type}] ${c.content}${c.source ? ` (source: ${c.source})` : ""}`)
+            .join("\n");
+        return ok(`${r.count} changes since ${args.since}:\n\n${list}`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// memory_cognitive_profile — Complete self-model (metacognition)
+server.tool("memory_cognitive_profile", "Get the brain's complete self-model: who the user is, their mood, active goals, top entities (people/places), learned procedures, and recent topics. Use for complete context awareness. No LLM cost — pure aggregation (~50ms).", {}, async () => {
+    try {
+        const r = (await api("GET", "/v1/personality/cognitive-profile"));
+        let out = `## Cognitive Profile\n\n`;
+        if (r.persona)
+            out += `**Persona:** ${r.persona}\n\n`;
+        if (r.mood)
+            out += `**Mood:** ${r.mood.current} (trend: ${r.mood.trend})\n\n`;
+        if (r.active_goals?.length)
+            out += `**Active Goals:**\n${r.active_goals.map((g) => `- ${g}`).join("\n")}\n\n`;
+        if (r.top_entities?.length)
+            out += `**Top Entities:** ${r.top_entities.map((e) => e.name || e).join(", ")}\n\n`;
+        if (r.procedures?.length)
+            out += `**Procedures:**\n${r.procedures.map((p) => `- ${p.slice(0, 100)}`).join("\n")}\n\n`;
+        if (r.recent_topics?.length)
+            out += `**Recent Topics:**\n${r.recent_topics.map((t) => `- ${t}`).join("\n")}\n`;
+        return ok(out.trim());
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// memory_entity_profile — Get everything known about an entity
+server.tool("memory_entity_profile", "Get complete profile for a specific entity (person, place, concept). Returns: frequency stats, linked memories, and relationships. Use when you need context about a specific person or topic the user has discussed.", {
+    name: z.string().describe("Entity name to look up (e.g. 'Sarah', 'React', 'AuthService')"),
+}, async (args) => {
+    try {
+        const r = (await api("GET", `/v1/entities/${encodeURIComponent(args.name)}/profile`));
+        if (!r.stats && !r.memories?.length)
+            return ok(`No information found about "${args.name}".`);
+        let out = `## Entity: ${args.name}\n\n`;
+        if (r.stats) {
+            out += `**Stats:** mentioned ${r.stats.frequency}x, recalled ${r.stats.recall_count}x`;
+            if (r.stats.first_seen)
+                out += `, first seen ${r.stats.first_seen.slice(0, 10)}`;
+            out += `\n\n`;
+        }
+        if (r.memories?.length) {
+            out += `**Linked Memories (${r.memory_count}):**\n`;
+            out += r.memories.map((m) => `- [${m.memory_type}] ${m.content}`).join("\n");
+            out += `\n\n`;
+        }
+        if (r.relationships?.length) {
+            out += `**Relationships (${r.relationship_count}):**\n`;
+            out += r.relationships.map((rel) => `- ${rel.source} → ${rel.relationship} → ${rel.target}`).join("\n");
+        }
+        return ok(out.trim());
+    }
+    catch (e) {
+        return err(e);
+    }
+});
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/kiro-setup.d.ts

@@ -0,0 +1,7 @@
+#!/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.
+ */
+export {};

package/dist/kiro-setup.js

@@ -0,0 +1,115 @@
+#!/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.
+ */
+import { createInterface } from "node:readline";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+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 writeIfMissing(filePath, content, label) {
+    if (existsSync(filePath)) {
+        console.log(`  skip  ${label} (already exists)`);
+        return false;
+    }
+    const dir = filePath.substring(0, filePath.lastIndexOf("/"));
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(filePath, content, "utf-8");
+    console.log(`  create  ${label}`);
+    return true;
+}
+const MCP_CONFIG = (apiKey, endpoint) => JSON.stringify({
+    mcpServers: {
+        memoryai: {
+            command: "npx",
+            args: ["-y", "memoryai-mcp"],
+            env: {
+                HM_API_KEY: apiKey,
+                HM_ENDPOINT: endpoint,
+            },
+        },
+    },
+}, 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
+`;
+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_...)"));
+    if (!apiKey) {
+        console.error("Error: API key is required. Set HM_API_KEY or enter it above.");
+        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
+`);
+    rl.close();
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "memoryai-mcp",
-  "version": "0.9.0",
-  "description": "MCP server for MemoryAI v0.9 — Personality Engine + Causal Reasoning. DNA-protected memories, Hebbian learning, Sleep consolidation, Personality synthesis, Timeline & WhatIf.",
+  "version": "2.1.0",
+  "description": "MCP server for MemoryAI — Long-term memory for AI agents. Works with Claude Code, Cursor, Windsurf, VS Code, Kiro.",
   "homepage": "https://memoryai.dev",
   "repository": {
     "type": "git",
@@ -10,7 +10,8 @@
   "type": "module",
   "main": "dist/index.js",
   "bin": {
-    "memoryai-mcp": "dist/index.js"
+    "memoryai-mcp": "dist/index.js",
+    "memoryai-kiro-setup": "dist/kiro-setup.js"
   },
   "scripts": {
     "build": "tsc",