Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
<div align="center">
Elephantasm
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
</div>
Model Context Protocol server for Elephantasm Long-Term Agentic Memory. One line of config.
Installation
pip install elephantasm-mcpQuick 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 |
|---|---|---|---|
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 + 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 elephantasm - TypeScript:
@elephantasm/client—npm install @elephantasm/client
Links
License
Apache 2.0