memoryai-mcp 0.9.0 → 1.5.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

@@ -36,7 +36,7 @@ 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.", {
     content: z.string().describe("What to remember"),
@@ -800,6 +800,76 @@ 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 (auto-detected from model if omitted)"),
+    model: z.string().optional().describe("Model name for auto-detecting context window size (e.g. claude-sonnet-4-6)"),
+}, async (args) => {
+    try {
+        const r = (await api("POST", "/v1/context/guard/check", {
+            estimated_tokens: args.estimated_tokens,
+            max_tokens: args.max_tokens || 0,
+            model: args.model || null,
+        }));
+        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. Returns task_id for async polling or result for blocking mode.", {
+    content: z.string().describe("Session transcript or content to compact"),
+    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.", {
+    task: z.string().describe("Task description for the new session"),
+    limit: z.number().optional().describe("Max memories to include (default: 10)"),
+}, async (args) => {
+    try {
+        const r = (await api("POST", "/v1/context/guard/bootstrap", {
+            task: args.task,
+            limit: args.limit || 10,
+        }));
+        return ok(`Bootstrap complete: ${r.memories_restored} memories (${r.dna_memories} DNA)\n` +
+            `Tokens used: ${r.tokens_used}\n\n` +
+            r.context_block);
+    }
+    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": "1.5.0",
+  "description": "MCP server for MemoryAI v1.5 — Living Brain for AI Agents. 5 biological behaviors (Remember, Forget, Connect, Sleep, Shield), DNA-protected memories, Hebbian learning, Multi-Agent Mesh, Personality synthesis, Causal reasoning.",
   "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",