Docs SDKs MCP Adapter

MCP Adapter

The @mnemexa/mcp package is a thin stdio adapter that exposes Mnemexa’s four endpoints as Model Context Protocol tools. Install it once and any MCP-compatible AI agent — Claude Desktop, Claude Code, Cursor, Windsurf, VS Code — gets shared, self-optimizing memory automatically.

Install

npx @mnemexa/mcp

The interactive installer detects your AI tools, prompts for your Mnemexa API key, writes the MCP server entry to each tool’s config, and injects a short instruction block into each tool’s rules file so the agent uses memory proactively.

Latest version: @mnemexa/mcp@2.0.4 on npm.

You need a Mnemexa API key. Get one at app.mnemexa.com — no credit card required.

Silent install

For CI scripts or AI-assisted setup:

npx @mnemexa/mcp --install YOUR_API_KEY

The four tools

The adapter exposes exactly four tools, one per backend endpoint:

ToolCallsWhat it does
brain.rememberPOST /v1/memory/storeSave important information. Auto-scored for importance, deduplicated, categorized. See memory.store.
brain.recallPOST /v1/memory/retrieveSemantic search over the workspace memory. Returns ranked, scored results. See memory.retrieve.
brain.healthGET /v1/optimize/healthMemory quality report — quality score, total count, stale/duplicate/overlong signals. See optimize.health.
brain.statusGET /v1/statusConnection check — returns workspace name, status, plan, key prefix. See status.

The four MCP tools mirror the four Python SDK methods exactly: brain.remember ↔ client.memory.store, brain.recall ↔ client.memory.retrieve, brain.health ↔ client.optimize.health, brain.status ↔ client.status. The MCP adapter is for AI agents; the Python SDK is for direct code; the underlying REST API serves both.

What the adapter does and doesn’t do

The adapter is intentionally thin — about 1,200 lines of TypeScript with no business logic. All intelligence (PII screening, deduplication, importance scoring, temporal classification, hybrid retrieval scoring, automatic decay) runs in Mnemexa’s cloud. The adapter’s only jobs are:

  1. Resolve the API key from MNEMEXA_API_KEY env var or ~/.mnemexa/config.json (with BIZX_API_KEY / ~/.bizxengine/config.json accepted as legacy fallbacks).
  2. Translate MCP tool calls into REST requests to api.mnemexa.com.
  3. Format responses for AI-readable display.
  4. Inject a short usage protocol into your IDE’s rules file so the agent calls brain.recall before answering and brain.remember when it learns something important.

Multi-agent memory

Same API key = same workspace = shared intelligence across every agent that uses it.

# Agent 1 — your laptop
npx @mnemexa/mcp --install mnx_ws_…

# Agent 2 — teammate's laptop
npx @mnemexa/mcp --install mnx_ws_…

# Agent 3 — CI / automation
npx @mnemexa/mcp --install mnx_ws_…

One agent learns that the client prefers morning standups. Every other agent on the workspace knows immediately on its next brain.recall. No prompt engineering, no manual context-pasting between agents.

Supported AI tools

The interactive installer auto-detects and configures:

  • Claude Desktop (Mac, Windows)
  • Claude Code (CLI)
  • Cursor
  • Windsurf
  • VS Code (with MCP extension)
  • OpenClaw — note: OpenClaw doesn’t inherit MCP servers from other tool configs. You’ll need to register mnemexa explicitly in ~/.openclaw/openclaw.json.

Any MCP-compatible tool not in the auto-config list can be wired up manually using the manual config snippet the installer prints at the end.

Environment variables

VariablePurpose
MNEMEXA_API_KEYPrimary API key source. Falls back to ~/.mnemexa/config.json.
BIZX_API_KEYLegacy fallback. Pre-rebrand keys continue to work.
MNEMEXA_BASE_URLOverride the API base URL. Used in dev. Falls back to BIZX_BASE_URL, then https://api.mnemexa.com.

Beyond auth and base URL, the adapter has zero runtime dependencies on environment variables. It adds roughly 5KB to your AI setup and has no business logic of its own to misconfigure.

Resources

← Previous TypeScript SDK