Elefante never forgets.
AI agents start every conversation from zero. Your preferences, decisions, and discovered patterns don't carry over. Elefante gives any MCP-compatible agent a persistent, local second brain — memories are stored, scored automatically, and surfaced at the right moment without being asked.
v2.10.0 — Persistent Memory Engine
┌─────────────────────────────────────────────────────────────┐
│ YOUR IDE (VS Code · Cursor · Windsurf · any MCP client) │
└────────────────────────┬────────────────────────────────────┘
│ MCP stdio
┌────────────────────────▼────────────────────────────────────┐
│ LAYER 1 · MCP PROTOCOL │
│ 16 tools · 2 prompts · Context Injection │
└────────────────────────┬────────────────────────────────────┘
│
┌────────────────────────▼────────────────────────────────────┐
│ LAYER 2 · INTELLIGENCE ENGINE │
│ Orchestrator · 5-signal scoring · Hybrid Memory │
│ (ChromaDB vectors + Kuzu graph) │
└────────────────────────┬────────────────────────────────────┘
│ snapshot.json
┌────────────────────────▼────────────────────────────────────┐
│ LAYER 3 · DASHBOARD │
│ Read-only view of your second brain's health │
│ http://127.0.0.1:8000 │
└─────────────────────────────────────────────────────────────┘
Every memory stored. Every context surfaced. Nothing forgotten.
Elefante is a local-first persistent memory engine for AI agents, connected via the Model Context Protocol (MCP).
- Stores facts, preferences, decisions, code patterns, and tasks
- Searches using hybrid retrieval — semantic vectors, knowledge graph, and session context
- Scores every memory automatically using 5 retrieval signals (semantic match, concept overlap, co-activation, authority, temporal freshness) — no manual ratings
- Injects context silently into every tool call — the agent gets relevant history without asking
- Connects knowledge through an entity-relationship graph
- Enforces quality via a compliance gate: search before write, no duplicates
- Visualizes brain health through a snapshot-driven dashboard
Everything runs locally. No cloud. No telemetry. Your data stays on your machine.
The interface between your IDE and the memory engine. 16 tools and 2 prompts let agents store, search, connect, and manage knowledge. A Compliance Gate prevents duplicates before they exist. Context Injection attaches relevant memories to every tool response. Directives enforce persistent behavioral rules that survive across sessions. Token Intelligence measures every response and tells the agent what each tool call costs — output tokens, protocol overhead, and signal ratio — so memory never becomes invisible bloat.
Full tool reference → docs/reference/tools.md IDE configuration → docs/how-to/configure-ide.md
Two storage backends working together:
- ChromaDB — 768-dimensional semantic vectors for meaning-based retrieval across months of history.
- Kuzu — a knowledge graph that tracks entities, relationships, and structural context.
- Behavioral Relevance — a 5-signal scoring system that automatically surfaces the most useful memories. No manual importance ratings.
Scoring details → docs/reference/scoring.md Architecture → docs/reference/architecture.md
A read-only view of your knowledge system, served from a lightweight snapshot so the agent stays fast:
- Health score with diagnostic panels
- Searchable, sortable memory table
- Topic distribution, memory insights, and a knowledge graph
Dashboard details → docs/how-to/view-dashboard.md Docker deployment → docs/how-to/docker.md
Elefante works with any MCP-compatible client today — VS Code, Cursor, Windsurf, and others. It is built to scale into fully autonomous agent frameworks (Docker-sandboxed, multi-agent, long-running) where persistent memory across sessions is not optional.
Requirements: Python 3.11+ (tested up to 3.13). Git is only required for the source-checkout fallback path.
Our installer detects your OS, manages the repository virtual environment, installs all deps, initializes local graph and vector databases, and automatically configures VS Code, Cursor, and Bob-IDE to connect to Elefante via MCP.
Release bundle (preferred): Download elefante-installer-<OS>.zip from GitHub Releases, extract it, then run the top-level install.sh or install.bat. The bootstrap places Elefante in a stable install root first, then delegates the real setup work to scripts/setup/install.py.
- macOS / Linux stable root:
~/.elefante/app/current - Windows stable root:
%LOCALAPPDATA%\Elefante\app\current
On macOS builders with Swift available, the DMG ships a native AppKit installer surface. The legacy Python/Tk installer is fallback compatibility only.
If .venv already exists, the installer offers four paths:
- Delete existing
.venvand install fresh (default) - Backup existing
.venvand install fresh - Reuse existing
.venv - Abort installation
If installation fails: read the persisted installer files in this order:
.elefante-install-summary.txt.elefante-install-status.txt.elefante-install.log
For release bundles and the macOS DMG, those files live in the stable install root. For source-checkout installs, they live in the repo root. The installer prints their exact paths at startup and on failure.
# Source checkout fallback
# macOS / Linux
git clone https://github.com/elefante/elefante.git
cd elefante
chmod +x install.sh && ./install.sh
# Windows
git clone https://github.com/elefante/elefante.git
cd elefante
install.batYou possess full local control. The installer automatically bridges into your IDE and injects a single "Seed Memory" to prove the connection.
The 60-Second Proof of Work:
- Restart your IDE.
- Open your AI Chat (Copilot, Cursor, etc).
- Copy/paste exactly this question:
What is my Elefante test passcode? - Watch the AI hit your local memory, cure its amnesia, and return the secret code.
Looking for manual setup or deep technical details? See the Full Installation Guide.
16 tools + 2 prompts. All names follow elefante-PascalCase convention.
| Category | Tools |
|---|---|
| Memory | elefante-Memory (actions: add · search · update · delete · consolidate) |
| Graph | elefante-GraphConnect, elefante-GraphQuery |
| Context | elefante-ContextGet, elefante-SessionsList |
| Tasks | elefante-TaskCreate, elefante-TaskUpdate, elefante-TaskGraph |
| ETL | elefante-ETLProcess, elefante-ETLClassify |
| Directives | elefante-DirectiveAdd, elefante-DirectiveList, elefante-DirectiveRemove |
| System | elefante-System, elefante-SystemStatusGet, elefante-DashboardOpen |
Full reference with parameter schemas → docs/reference/tools.md
Elefante keeps durable architecture rules out of the live prompt by separating lightweight agent instructions from retrieved knowledge:
- Keep the instruction file small. Your
.cursorrules,copilot-instructions.md, or equivalent should tell the agent to search Elefante before writing code or declaring work complete. - Store durable rules in Elefante. Architecture contracts, schemas, and team process belong in
specificationordirectivememories rather than inside a giant prompt file. - Retrieve only what is relevant. When the agent searches, Elefante surfaces the specific rule needed for the current task instead of injecting an entire handbook into every prompt.
| Purpose | Technology |
|---|---|
| Vector store | ChromaDB 1.3.5 |
| Graph store | Kuzu 0.11.3 |
| Embeddings | sentence-transformers (gte-base) |
| Protocol | MCP 1.23.1 |
| Dashboard | React + TypeScript + Vite |
| Runtime | Python 3.11 |
src/ Core engine, MCP server, dashboard
docs/ Technical reference, guides, debug compendiums
examples/ Agent tutorial and integration patterns
tests/ Unit, integration, and verification tests
scripts/ Setup, deployment, and maintenance tools
Three audiences, three surfaces (v2.10.0 split, see [workspace/PLANNING.md §2.5](workspace/PLANNING.md §2.5)):
| Audience | Start here |
|---|---|
| Using Elefante as a memory engine | docs/user/README.md |
| Building or debugging Elefante itself | agents/orchestrator.md → then docs/developer/README.md |
| Loading an agent protocol at the moment of failure | agents/ |
| Symptom | Load |
|---|---|
| Building a feature, debugging Elefante itself | agents/orchestrator.md |
Any MemoryAdd / MemoryUpdate / MemoryDelete (auto) |
agents/memory-janitor.md |
| "What do I have stored?", export, audit | agents/memory-inspector.md |
| Install failed, broken venv, repair | agents/installer.md |
| MCP tools missing in IDE, server stuck | agents/restarter.md |
| Backup, restore, factory reset, restart | agents/operator.md |
| Version bump, CHANGELOG, tag, release | agents/release-manager.md |
| Line of attack is suspect (RESEARCH mode) | agents/researcher.md |
| Need to retune the rules themselves | agents/puppeteer.md (PRIVILEGED only) |
- Tool reference — parameter schemas for all 16 tools and 2 prompts
- Behavioral Relevance — how automatic scoring works
- Installation — step-by-step setup
- Architecture — system design
- Dashboard — visualization and health monitoring
- Docker — containerized deployment
- Debugging — known issues tracker, compendium routing, and verification commands
Every tagged Elefante release is documented in three places:
- GitHub Releases — packaged binaries and release-specific notes
- CHANGELOG.md — the full historical ledger
- README.md — the current product surface, install path, and docs map
Release bodies are rendered from the matching CHANGELOG.md entry in CI, so new tags do not ship with empty GitHub release pages. CHANGELOG.md is the authoritative historical record for older releases as well, including legacy GitHub release pages that predate rendered release bodies.
Do not cut or push a v* tag until its matching CHANGELOG.md entry exists.
See CONTRIBUTING.md.
License: Business Source License 1.1 — free for non-competitive use. Converts to Apache 2.0 on 2029-02-10.