memoryai-mcp 2.2.0 → 2.3.1

package/README.md

@@ -1,304 +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.**
-
-## Quick Start (2 minutes)
-
-### 1. 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}'
-```
-
-Save the `api_key` from the response. You'll need it below.
-
-### 2. Pick Your IDE/Tool
-
-Choose your platform below. Config once — memory works automatically forever.
-
----
-
-## IDE Setup
-
-### Claude Code (CLI) — `~/.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` 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
-{
-  "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