MemoryAI Home Setup Docs

Setup MemoryAI

Pick your mode. Install in 2 minutes. Works with any MCP-compatible IDE.

Use the MemoryAI extension instead

Kiro · Cursor · Windsurf · VS Code — paste your API key, done. The extension wires the MCP server, hooks, and rules automatically.

VS Marketplace Open VSX

Or via CLI: code --install-extension memoryai.memoryai-vsx · then run MemoryAI: Connect from the command palette.

— or configure manually below (Claude Code / Codex CLI / curl) —

Choose Your Mode

npx memoryai-claude installCopy

npx memoryai-claude doctor     # verify hooks + ping server
npx memoryai-claude status     # show hook scope (user/project)
npx memoryai-claude uninstall  # remove hooks, keep server dataCopy

claude mcp add memoryai -s user \
  -e HM_API_KEY=hm_sk_YOUR_KEY \
  -e HM_ENDPOINT=https://memoryai.dev \
  -e HM_COMPACT_AT=100000 \
  -e HM_CRITICAL_AT=150000 \
  -- npx -y memoryai-mcpCopy

{
  "mcpServers": {
    "memoryai": {
      "command": "npx",
      "args": ["-y", "memoryai-mcp"],
      "env": {
        "HM_API_KEY": "hm_sk_YOUR_KEY",
        "HM_ENDPOINT": "https://memoryai.dev",
        "HM_COMPACT_AT": "100000",
        "HM_CRITICAL_AT": "150000"
      }
    }
  }
}Copy

{
  "mcpServers": {
    "memoryai": {
      "command": "npx",
      "args": ["-y", "memoryai-mcp"],
      "env": {
        "HM_API_KEY": "hm_sk_YOUR_KEY",
        "HM_ENDPOINT": "https://memoryai.dev",
        "HM_COMPACT_AT": "100000",
        "HM_CRITICAL_AT": "150000"
      }
    }
  }
}Copy

{
  "servers": {
    "memoryai": {
      "command": "npx",
      "args": ["-y", "memoryai-mcp"],
      "env": {
        "HM_API_KEY": "hm_sk_YOUR_KEY",
        "HM_ENDPOINT": "https://memoryai.dev",
        "HM_COMPACT_AT": "100000",
        "HM_CRITICAL_AT": "150000"
      }
    }
  }
}Copy

{
  "mcpServers": {
    "memoryai": {
      "command": "npx",
      "args": ["-y", "memoryai-mcp"],
      "env": {
        "HM_API_KEY": "hm_sk_YOUR_KEY",
        "HM_ENDPOINT": "https://memoryai.dev",
        "HM_COMPACT_AT": "100000",
        "HM_CRITICAL_AT": "150000"
      }
    }
  }
}Copy

# MemoryAI

## Session Start
Call `memory_bootstrap` to load context from previous sessions.

## During Session
- Preference learned → `memory_store` (memory_type="preference")
- Decision made → `memory_store` (memory_type="decision")
- Need past context → `memory_recall`

## Context Guard (every ~15 messages)
Call `context_guard_check` with estimated_tokens and max_tokens.
If "compact_now" → call `context_guard_compact` with summary.Copy

claude mcp add memoryai -s user \
  -e HM_API_KEY=hm_sk_YOUR_KEY \
  -e HM_ENDPOINT=https://memoryai.dev \
  -- npx -y memoryai-mcpCopy

{
  "mcpServers": {
    "memoryai": {
      "command": "npx",
      "args": ["-y", "memoryai-mcp"],
      "env": {
        "HM_API_KEY": "hm_sk_YOUR_KEY",
        "HM_ENDPOINT": "https://memoryai.dev"
      }
    }
  }
}Copy

{
  "mcpServers": {
    "memoryai": {
      "command": "npx",
      "args": ["-y", "memoryai-mcp"],
      "env": {
        "HM_API_KEY": "hm_sk_YOUR_KEY",
        "HM_ENDPOINT": "https://memoryai.dev"
      }
    }
  }
}Copy

# MemoryAI

## Session Start
Call `memory_bootstrap` to load context.

## During Session
- Preference → `memory_store` (memory_type="preference")
- Decision → `memory_store` (memory_type="decision")
- Need context → `memory_recall`Copy

claude mcp add memoryai -s user \
  -e HM_API_KEY=hm_sk_YOUR_KEY \
  -e HM_ENDPOINT=https://memoryai.dev \
  -e HM_COMPACT_AT=100000 \
  -e HM_CRITICAL_AT=150000 \
  -- npx -y memoryai-mcpCopy

{
  "mcpServers": {
    "memoryai": {
      "command": "npx",
      "args": ["-y", "memoryai-mcp"],
      "env": {
        "HM_API_KEY": "hm_sk_YOUR_KEY",
        "HM_ENDPOINT": "https://memoryai.dev",
        "HM_COMPACT_AT": "100000",
        "HM_CRITICAL_AT": "150000"
      }
    }
  }
}Copy

# Context Guard

## Every ~15 messages
Call `context_guard_check` with estimated_tokens and max_tokens.
- "safe" → continue
- "compact_soon" → prepare summary
- "compact_now" → call `context_guard_compact` immediatelyCopy

Threshold Settings

Control when Context Guard triggers. Lower = more aggressive (compact earlier).

Note: v2.3.2+ uses absolute token counts instead of percentages. Pick numbers that match the cost ceiling you want — they apply uniformly across every model, independent of the underlying context window.

Recommended Presets

What happens at each threshold (1M context example)

Model Detection

Context Guard now uses absolute token thresholds (HM_COMPACT_AT / HM_CRITICAL_AT) — no model-window detection required. Pick numbers that match your cost ceiling and you're done.

Troubleshooting

Context Guard doesn't trigger

• Use absolute token thresholds — HM_COMPACT_AT and HM_CRITICAL_AT in tokens (e.g. 100000 / 150000), not percentages
• Check your AI instructions include the context_guard_check call
• Verify MCP connection: tool should appear in IDE's tool list

MCP not connecting

# Test manually:
HM_API_KEY=hm_sk_your_key npx memoryai-mcp
# Should print: "MemoryAI MCP server running"

# Check server:
curl https://memoryai.dev/health
# Should return: {"status": "ok"}

Change thresholds after install

# Override per-request (preferred — absolute tokens):
curl -X POST -H "Authorization: Bearer hm_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"turn_count": 30, "compact_at_tokens": 100000, "critical_at_tokens": 150000}' \
  https://memoryai.dev/v1/ide/guard/turn-check

# Or just edit HM_COMPACT_AT / HM_CRITICAL_AT in your IDE config and restart.Copy

MemoryAI — A living brain for AI agents.
Home · Full Docs · GitHub