elephantasm-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@elephantasm-mcp search my knowledge for best practices in error handling"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.

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-mcpRelated 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-mcpConfiguration
Variable | Required | Default | Description |
| Yes | — | Your API key (starts with |
| No | — | Default anima ID (can be overridden per tool call) |
| No |
| 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 |
| string | required | Natural language search query |
| string | env default | Override default anima |
| string[] | all | Filter: |
| int | 2000 | Token budget for results |
| int | 20 | Max results |
| 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 |
| string | required | Search query |
| string | env default | Override default anima |
| int | 10 | Max results |
| 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 |
| string | required | Search query |
| string | env default | Override default anima |
| int | 10 | Max results |
| float | 0.7 | Min similarity (0–1) |
| string | — | Filter: |
get_identity — Read the agent's personality
Retrieve the agent's behavioral fingerprint: personality type, communication style, and self-reflection.
Parameter | Type | Default | Description |
| 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 |
| string | required | Event content |
| string |
|
|
| string | env default | Override default anima |
| string | — |
|
| string | — | Who generated this event |
| string | — | Group related events |
Resources
Two resources provide context that MCP clients can embed directly into system prompts:
URI | Type | Description |
|
| Latest compiled memory pack — memories, knowledge, identity, and temporal context assembled into a single prompt-ready string |
|
| 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 + pgVectorWrite 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 elephantasmTypeScript:
@elephantasm/client—npm install @elephantasm/client
Links
License
Apache 2.0
Available Tools
5 toolsget_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
Scored across 5 tools
There is overlap between 'query', 'search_knowledge', and 'search_memories', as all three perform semantic search; descriptions help differentiate but ambiguity remains.
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.
5 tools is well-scoped for the domain of managing an Anima's identity, events, and memory; each tool serves a clear purpose.
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
Related MCP Connectors
An MCP memory server. One memory your agents share — across models, devices and apps.
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Persistent memory for AI agents to retain, retrieve, and recall conversation context through MCP.
Hosted memory for AI agents over MCP. One memory shared by all your agents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn 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.1MIT
- FlicenseNot gradedqualityBmaintenanceA persistent memory server for AI agents using MCP protocol, enabling semantic storage and retrieval of dialogues, documents, and agent states.-
- AlicenseAqualityBmaintenanceAn MCP server providing long-term memory for AI agents with forgetting curves, consolidation, and graph-based retrieval.1014 npmMIT
- AlicenseNot gradedqualityCmaintenanceMCP 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.2MIT