Skip to main content
Glama
elephantasm-mcp
by kaminocorp

Elephantasm

elephantasm-mcp

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

PyPI version Python 3.10+ License

Website · Docs · PyPI · GitHub


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

Installation

pip install elephantasm-mcp

Related MCP server: Selti

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

Variable

Required

Default

Description

ELEPHANTASM_API_KEY

Yes

—

Your API key (starts with sk_live_)

ELEPHANTASM_ANIMA_ID

No

—

Default anima ID (can be overridden per tool call)

ELEPHANTASM_ENDPOINT

No

https://api.elephantasm.com/api

API endpoint

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

Parameter

Type

Default

Description

query

string

required

Natural language search query

anima_id

string

env default

Override default anima

sources

string[]

all

Filter: "memories", "knowledge", "identity"

max_tokens

int

2000

Token budget for results

limit

int

20

Max results

exclude_ids

string[]

—

Exclude IDs for multi-turn dedup

search_memories — Find past experiences

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

Parameter

Type

Default

Description

query

string

required

Search query

anima_id

string

env default

Override default anima

limit

int

10

Max results

threshold

float

0.7

Min similarity (0–1)

search_knowledge — Look up what the agent knows

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

Parameter

Type

Default

Description

query

string

required

Search query

anima_id

string

env default

Override default anima

limit

int

10

Max results

threshold

float

0.7

Min similarity (0–1)

knowledge_type

string

—

Filter: FACT, CONCEPT, METHOD, PRINCIPLE, EXPERIENCE

get_identity — Read the agent's personality

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

Parameter

Type

Default

Description

anima_id

string

env default

Override default anima

ingest_event — Record an interaction

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

Parameter

Type

Default

Description

content

string

required

Event content

event_type

string

message.in

message.in, message.out, tool.call, tool.result, system

anima_id

string

env default

Override default anima

role

string

—

user, assistant, system, tool

author

string

—

Who generated this event

session_id

string

—

Group related events

Resources

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

URI

Type

Description

anima://{id}/pack

text/plain

Latest compiled memory pack — memories, knowledge, identity, and temporal context assembled into a single prompt-ready string

anima://{id}/identity

application/json

Identity profile — personality type, communication style, self-reflection

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:

License

Apache 2.0

Available Tools

5 tools
get_identityB

Get an Anima's identity profile — personality type, communication style, and self-reflection data.

Inputs: anima_id.

ingest_eventA

Record an interaction event for future memory synthesis. Use this to capture messages, tool calls, or other signals that should become part of the Anima's long-term memory.

Inputs: content (required), event_type, anima_id, role, +2 more.

queryA

Search an Anima's brain across memories, knowledge, and identity. Returns relevant results ranked by semantic similarity to your query. Use this for general questions about what the Anima knows or remembers.

Inputs: query (required), anima_id, sources, max_tokens, +2 more.

search_knowledgeA

Semantic search across an Anima's knowledge base. Returns canonicalized truths (facts, concepts, methods, principles, experiences) ranked by similarity. Use this for structured knowledge retrieval.

Inputs: query (required), anima_id, limit, threshold, +1 more.

search_memoriesA

Semantic search across an Anima's memories. Returns memories ranked by similarity to your query. Use this when you want to find specific past experiences or interactions.

Inputs: query (required), anima_id, limit, threshold.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 5 tools

    Disambiguation3/5

    There is overlap between 'query', 'search_knowledge', and 'search_memories', as all three perform semantic search; descriptions help differentiate but ambiguity remains.

    Naming Consistency3/5

    Most tools follow a verb_noun pattern (get_identity, ingest_event, search_knowledge, search_memories), but 'query' is a single verb without a noun, breaking consistency.

    Tool Count5/5

    5 tools is well-scoped for the domain of managing an Anima's identity, events, and memory; each tool serves a clear purpose.

    Completeness3/5

    Core operations (get identity, record events, search) are present, but missing update/delete for identity and events, and no explicit tool to add knowledge directly.

    Maintenance

    ActivityStale
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that provides persistent long-term memory for AI agents via local SQLite storage with low token overhead, enabling memory storage, retrieval, and management across sessions.
      1
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      A persistent memory server for AI agents using MCP protocol, enabling semantic storage and retrieval of dialogues, documents, and agent states.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server that provides AI agents with persistent memory, cross-agent sharing, and context management, enabling them to remember conversations, track complex tasks, and evolve skills across tools.
      2
      MIT