memoryai-mcp

MCP server for MemoryAI — 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:

# 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.

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.

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

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.

If you prefer not to use hooks, add the MCP server to ~/.claude/settings.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:

## 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.

Kiro — one command, fully automatic

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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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 | | Enterprise | Everything + deep graph traversal + on-prem | Custom |

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