elephantasm-mcp

MCP server for long-term agent memory. Give any AI agent persistent memory, searchable knowledge, and an evolving identity.

Website · Docs · PyPI · GitHub

Model Context Protocol server for Elephantasm Long-Term Agentic Memory. One line of config.

Installation

pip install elephantasm-mcp

Quick Start

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "elephantasm": {
      "command": "elephantasm-mcp",
      "env": {
        "ELEPHANTASM_API_KEY": "sk_live_...",
        "ELEPHANTASM_ANIMA_ID": "your-anima-id"
      }
    }
  }
}

Claude Code

Add to .claude/settings.json or ~/.claude/settings.json:

{
  "mcpServers": {
    "elephantasm": {
      "command": "elephantasm-mcp",
      "env": {
        "ELEPHANTASM_API_KEY": "sk_live_...",
        "ELEPHANTASM_ANIMA_ID": "your-anima-id"
      }
    }
  }
}

Cursor / Windsurf

Add to your MCP config (Settings > MCP Servers):

{
  "elephantasm": {
    "command": "elephantasm-mcp",
    "env": {
      "ELEPHANTASM_API_KEY": "sk_live_...",
      "ELEPHANTASM_ANIMA_ID": "your-anima-id"
    }
  }
}

Any MCP-Compatible Agent

The server uses stdio transport — any MCP client that can spawn a subprocess works out of the box:

ELEPHANTASM_API_KEY=sk_live_... ELEPHANTASM_ANIMA_ID=... elephantasm-mcp

Configuration

Get your API key and anima ID from the Elephantasm dashboard.

Tools

Five tools give your agent full read/write access to its memory:

query — Search the brain

Cross-source semantic search across memories, knowledge, and identity in one call. Returns a pre-formatted context string ready for system prompt injection.

query("what does the user prefer for error handling")

search_memories — Find past experiences

Semantic search across structured memories (reflections on past interactions).

search_knowledge — Look up what the agent knows

Semantic search across canonicalized knowledge — facts, concepts, methods, principles, and experiences.

get_identity — Read the agent's personality

Retrieve the agent's behavioral fingerprint: personality type, communication style, and self-reflection.

ingest_event — Record an interaction

Capture a message, tool call, or system event. Queued for automatic memory synthesis.

Resources

Two resources provide context that MCP clients can embed directly into system prompts:

How It Works

Elephantasm is a Long-Term Agentic Memory framework. The MCP server connects your agent to its memory backend:

Your Agent ←→ elephantasm-mcp ←→ api.elephantasm.com ←→ PostgreSQL + pgVector

Write path: ingest_event → Events accumulate → Memory Synthesis (LLM) → Knowledge Synthesis (LLM) → Identity evolution

Read path: query / search_memories / search_knowledge → pgVector semantic search → scored, formatted results

Memory is curated automatically by two background loops:

• Dreamer — decays, merges, splits, and archives memories

• Meditator — clusters, merges, reclassifies, and refines knowledge

SDKs

For programmatic access without MCP, use the native SDKs:

• Python: elephantasm — pip install elephantasm

• TypeScript: @elephantasm/client — npm install @elephantasm/client

Links

• Documentation

• Dashboard

• GitHub

• API Reference

License

Apache 2.0