Elefante

Elefante

The open, Git-native memory protocol for MCP agents: portable, inspectable, versioned, and human-editable.

Your agent's memory is a Git repo you own.Every memory is a Markdown file you can read.Every change is a commit you can audit.Any MCP agent can connect to it.

Why

Every AI agent has its own memory system. Claude's works only with Claude. ChatGPT's works only with ChatGPT. They're all opaque, vendor-locked, and non-portable.

Elefante takes a different approach. Instead of optimizing for retrieval quality, it optimizes for ownership, auditability, and portability — the things that matter when memory is a first-class asset, not a hidden implementation detail.

Quick Start

# Installnpm install -g elefante-mcp
# Initialize vault (uses a private GitHub repo as storage)elefante init [email protected]:yourname/my-memory.git
# Add your first memoryelefante add \  --name "TypeScript strict mode" \  --type user \  --body "Always enable strict: true in tsconfig.json"
# Searchelefante search "typescript"
# Check statuselefante status

Connect to Your Agent

From the terminal (before starting Claude Code):

claude mcp add --scope user elefante -- npx -y elefante-mcp mcp

From inside Claude Code (during a session):

/mcp add --scope user elefante -- npx -y elefante-mcp mcp

Or manually — add to your MCP config (~/.claude.json, .cursor/mcp.json, etc.):

{  "mcpServers": {    "elefante": {      "command": "npx",      "args": ["-y", "elefante-mcp", "mcp"]    }  }}

Cursor / VS Code / Codex — same config. Any agent that speaks MCP can read and write to the same vault.

Once connected, your agent gets 7 tools: memory_write, memory_read, memory_search, memory_list, memory_update, memory_delete, memory_sync.

Auto-Discovery

Elefante injects your top memories directly into the agent's system prompt at startup via MCP instructions. The agent sees your preferences, feedback, and project context without needing to search first.

No CLAUDE.md hacks. No "search my elefante memory" prompts. It just works.

Project-Aware Memory

Elefante auto-detects which project you're in and scopes memories accordingly. No configuration needed.

How It Works

When the MCP server starts, it reads the git remote from your working directory:

~/Projects/acme-api/   →  git remote = github.com:you/acme-api.git                       →  profile = "you/acme-api"                       →  memories scoped to this project
~/Projects/my-cli/     →  git remote = github.com:you/my-cli.git                       →  profile = "you/my-cli"                       →  different project, different memories

What Gets Scoped

The agent decides based on context. User preferences and behavioral feedback are typically global. Project details and references are typically scoped.

What You See When You Search

Working in acme-api:  ✓ "Uses Postgres 16"              (profile: you/acme-api)  ✓ "Prefers Bun over npm"          (profile: null — global)  ✗ "Uses SQLite"                   (profile: you/my-cli — different project)
Working in my-cli:  ✓ "Uses SQLite"                   (profile: you/my-cli)  ✓ "Prefers Bun over npm"          (profile: null — global)  ✗ "Uses Postgres 16"             (profile: you/acme-api — different project)

Global memories always show up. Project memories only show up in their project.

Escape Hatches

What a Memory Looks Like

Every memory is a Markdown file with YAML frontmatter. You can open it in any editor.

---id: mem_a1b2c3d4e5f6type: feedbackname: No database mocking in testsdescription: Integration tests must use real database connectionsprofile: you/acme-apiimportance: 3tags: [testing, database]created_at: "2026-04-14T10:30:00Z"updated_at: "2026-04-14T14:22:00Z"---
Do not mock the database in integration tests — use a real connectionto a test database.
**Why:** Mocked tests passed but the production migration failed becausethe mock didn't reflect actual schema constraints.
**How to apply:** Use the test database helper (`createTestDb()`)instead of jest mocks.

What a Git Log Looks Like

$ git log --onelinef4a2c1e remember: No database mocking in testsb3d8e7a remember: TypeScript strict mode preferencea1c9f2b update: REST to GraphQL migration deadline9e7d4c3 forget: Outdated staging URL2f8a6b1 Initialize elefante vault

Every write is remember:. Every update is update:. Every delete is forget:. Your memory has a clean, auditable history.

Vault Structure

~/.elefante/vault/├── .elefante/│   └── config.yaml              # Vault settings├── memories/│   ├── user/                    # Who the user is│   │   └── mem_*.md│   ├── feedback/                # How the agent should behave│   │   └── mem_*.md│   ├── project/                 # Active work context│   │   └── mem_*.md│   └── reference/               # External resource pointers│       └── mem_*.md├── profiles/│   └── *.yaml                   # Named scopes for partitioning└── index/    ├── manifest.json            # All memory metadata (generated)    └── search.json              # Search index (generated)

Memory Types

Four types. Intentionally constrained — a small taxonomy forces good classification.

Authentication

Elefante doesn't reinvent auth. It uses whatever Git credentials you already have.

Resolution order:

1. Local git credentials (SSH keys, macOS Keychain, credential helpers)
2. gh auth token (if GitHub CLI is installed)
3. ELEFANTE_GITHUB_TOKEN environment variable
4. ~/.elefante/config.json token field

If git or gh is authenticated, Elefante works with zero config.

CLI Reference

elefante init <repo-url>       Clone vault repo to ~/.elefante/vault/elefante status                Vault status, sync state, memory countelefante list [--type TYPE]    List memories with filterselefante search <query>        Search by keywordelefante read <id>             Read a specific memoryelefante add                   Create a memoryelefante delete <id>           Delete a memoryelefante sync                  Pull and push changeselefante reindex               Rebuild search indexelefante mcp                   Start MCP stdio server

How It Compares

Elefante doesn't compete on retrieval quality. It competes on ownership.

"Why not Obsidian + MCP plugin?" — Obsidian is a tool for humans that agents can access. Elefante is a tool for agents that humans can access. Same data format (Markdown + Git), different design center.

Protocol

The full protocol specification — memory model, vault structure, MCP interface, concurrency model, indexing, security considerations — is in PROTOCOL.md.

License

MIT