🐘 The Philosophy

Legend says elephants remember watering holes across decades of shifting sands. Modern AI agents, on the other hand, forget your preferences the moment their context window slides shut.

Elephantine gives your agents permanent, unshakeable memory. Built from the ground up for standard commodity CPUs (2 vCPU / 4 GB RAM), Elephantine requires zero GPUs, makes zero external API calls, and enforces zero data leakage by storing everything directly on host disk via embedded LanceDB and SQLite.

---

⚡ Highlights

• 🏎 100% CPU-Native Execution: Sub-35ms recall latency on 2 vCPU servers powered by ONNX Runtime with AVX-512 SIMD thread pinning. No CUDA. No PyTorch bloat.
• 👥 Multi-Agent Shared Workspace: Seamless memory pooling (workspace_id) across teams (Coder, Tester, Architect) with Role-Based Authority Consensus (role_authority) preventing junior agents from overwriting senior architectural decisions.
• 📊 Built-in WebUI Inspector & Knowledge Graph: Real-time interactive dashboard (/dashboard) featuring memory ledgers and a Cytoscape.js interactive graph visualizer for entity relationships.
• 🦙 In-Process GGUF SLM Extraction: Local structured memory extraction via embedded llama-cpp-python (Qwen2.5-0.5B-Instruct), requiring zero background LLM servers.
• 🕸 Graph Memory & Knowledge Triplets: Native subject-predicate-object semantic graphs (/graph/query) integrated directly into the hybrid retrieval pipeline.
• ⚙️ Procedural Memory & Workflow Tracking: Records tool execution histories and learned multi-step procedural patterns (/procedural/track).
• 🔒 Local-First & Zero Leakage: Embedded LanceDB (Arrow/C++) vector store + SQLite WAL. Data never leaves your host filesystem.
• 🔌 Universal Agent Support (MCP & REST): Plugs directly into Google Antigravity, OpenAI Codex, Cursor Composer, GitHub Copilot, Windsurf, and Claude Desktop with 1-click automatic CLI installers.
• 🛡️ Enterprise RBAC & Security: Configurable RoleBasedAuthEngine with granular role permissions (admin, architect, editor, viewer) and API Key / Bearer token enforcement.

---

⚖️ Why Elephantine?

Feature / Metric	Cloud Memory / Hosted RAG	Traditional Vector DBs	🐘 ELEPHANTINE
GPU Dependency	Mandatory / Cloud-billed	Frequently required	Zero (100% CPU Native)
Data Privacy	Leaks to 3rd-party cloud	Hosted servers	100% Host Local (Embedded)
Memory Dimensions	Semantic only	Vector embeddings only	Semantic + Procedural + Graph
Multi-Agent Teams	Shared tenant silos	No built-in consensus	Workspace Pooling + Role Authority
Cold-Start RAM	N/A (External service)	1.5 GB - 4 GB+	< 400 MB
Recall Latency (CPU)	120ms - 400ms (Network)	50ms - 150ms	~35ms (p50)
Operational Cost	$20 - $200+/mo per agent	Dedicated VM costs	$0.00 (Runs on existing host)
MCP Integration	Manual API glue	Custom wrappers required	Native 1-Click (stdio / sse)

---

🏗️ Architecture

---

🚀 Quick Start & CLI Installation

1. Install the Elephantine CLI

Installing Elephantine automatically makes the elephantine command globally available in your terminal:

# Recommended: Standalone global CLI via pipx
pipx install elephantine

# Or with uv
uv tool install elephantine

# Or standard pip
pip install elephantine

2. Start the Engine Server & WebUI Dashboard

elephantine start --port 8765

Open your browser to http://localhost:8765/dashboard to view the live Memory Inspector!

Option B: From Source (For Contributors)

# 1. Clone repository
git clone https://github.com/partitect/elephantine.git
cd elephantine

# 2. Setup virtual environment with uv
uv venv .venv
# Windows: .venv\Scripts\activate | Linux/macOS: source .venv/bin/activate
uv pip install -e ".[dev]"

# 3. Start the engine server & dashboard
elephantine start --port 8765

---

🔌 1-Click IDE & Agent Setup (MCP)

Elephantine connects to all major agentic IDEs, coding assistants, and desktop AI clients via native Model Context Protocol (MCP).

⚡ 1-Second Automatic CLI Installers

With the elephantine CLI installed, configure your favorite AI agent environment in seconds with zero manual JSON editing:

# Google Antigravity (AGY)
elephantine install-antigravity

# OpenAI Codex & GitHub Copilot
elephantine install-codex

# Cursor Composer & Editor
elephantine install-cursor

# Claude Desktop
elephantine install-claude

# VS Code Workspace (.vscode/settings.json)
elephantine install-vscode

Manual Configuration

You can also view ready-to-paste configurations manually anytime:

elephantine config-antigravity
elephantine config-codex
elephantine config-cursor
elephantine config-claude

---

💻 Direct Terminal CLI Commands

Manage and inspect memories directly from your terminal without opening a browser or writing scripts:

# 1. Remember a fact with workspace and authority
elephantine remember "PostgreSQL 16 with pgvector extension is required" \
  --workspace phoenix-core \
  --category architecture \
  --authority 1.0

# 2. Recall memories via hybrid dense + BM25 search
elephantine recall "which database engine are we using?" \
  --workspace phoenix-core \
  --top-k 3

# 3. Register a proactive trigger (recurring or absolute)
elephantine trigger-create "Today is Friday! Weekly progress report is due at 17:00." \
  --trigger "weekly:FRI:17:00" \
  --workspace phoenix-core \
  --agent coder_agent

# 4. Pull pending unacknowledged proactive alerts
elephantine trigger-pending --agent coder_agent --workspace phoenix-core

---

🔔 Proactive Memory Triggers (Autonomous Memory Feeds)

Traditional memory systems (such as Mem0) are purely reactive: an AI agent must explicitly execute a query (/recall) to know what it remembered.

Elephantine introduces Proactive Memory Triggers: The engine actively stages alerts and feeds critical context to agents without requiring prompt lookups, based on:

• Recurring Schedules: weekly:FRI:17:00 (e.g. weekly reports), daily:09:00 (morning standups).
• Time Intervals: every:30m, every:2h, every:1d (cache invalidations, health checks).
• Exact Timestamps: ISO-8601 datetimes (2026-09-15T10:00:00Z).

Delivery Modes:

1. Pull-Based Check-in (Zero-Latency): Ajan seans başlattığında ya da döngü içinde bekleyen bildirimleri çeker:

   alerts = client.get_pending_alerts(target_agent="coder_agent", workspace_id="phoenix-core")
   for alert in alerts:
       print(f"Proactive context: {alert['content']}")
       client.acknowledge_alert(alert['trigger_id'])
   

2. Real-Time Streaming (SSE): Listen to live proactive triggers via GET /proactive/stream.
3. HTTP Webhooks: Configure webhook_url to receive instant asynchronous POST notifications.

---

👥 Multi-Agent Shared Workspace

Coordinate agent teams (e.g. Coder, Tester, Architect) with persistent memory pools and hierarchical authority protection:

from elephantine.client import ElephantineClient

# Connect to local Elephantine daemon
client = ElephantineClient("http://127.0.0.1:8765")

# 1. Lead Architect sets architectural baseline (Authority: 1.0)
client.remember(
    content="Database must strictly run PostgreSQL 16 with pgvector extension.",
    category="architecture",
    entity_key="project:db_engine",
    workspace_id="phoenix-core",
    role_authority=1.0
)

# 2. Junior Coder attempts to change database (Authority: 0.3)
# -> REJECTED by Role Authority Consensus (protected against lower authority)
client.remember(
    content="Let's switch project database to SQLite for simplicity.",
    category="architecture",
    entity_key="project:db_engine",
    workspace_id="phoenix-core",
    role_authority=0.3
)

# 3. Tester Agent recalls workspace memories (Authority-weighted re-ranking)
results = client.recall(
    query="Which database engine are we using?",
    workspace_id="phoenix-core"
)

# Output guarantees PostgreSQL 16 is preserved:
# [architecture] (Authority: 1.0) -> Database must strictly run PostgreSQL 16...

---

🖥️ WebUI Dashboard & Interactive Knowledge Graph

Elephantine includes a built-in, lightweight inspector accessible at http://localhost:8765/dashboard:

• Real-Time Memory Ledger: Inspect active vs deprecated memories, view revision counts and superseded states.
• 🕸 Interactive Knowledge Graph (Cytoscape.js): Explore semantic entities and subject-predicate-object triplets with force-directed (CoSE), circular, and concentric layouts.
• Click-to-Inspect: Tap any node or relationship edge to view confidence scores, source memories, and linked attributes.
• Authority & Conflict Tracking: Monitor role-based modifications and LWW (Last-Write-Wins) deprecation chains.

---

💻 SDKs & Integrations

1. Python SDK & LangChain Integration

import asyncio
from elephantine.client import AsyncElephantineClient, ElephantineLangChainMemory

async def main():
    async with AsyncElephantineClient("http://127.0.0.1:8765") as client:
        await client.remember(
            content="User prefers pytest with async test runners.",
            category="preference",
            entity_key="dev:test_runner",
            workspace_id="dev-team",
            role_authority=0.8
        )

        res = await client.recall(
            query="test runner preferences",
            workspace_id="dev-team",
            top_k=3
        )
        print("Recalled:", res)

    # LangChain Memory Adapter
    chain_memory = ElephantineLangChainMemory(
        base_url="http://127.0.0.1:8765",
        workspace_id="dev-team"
    )
    chain_memory.save_context({"input": "Hello"}, {"output": "I remember your preferences!"})

if __name__ == "__main__":
    asyncio.run(main())

2. TypeScript / Node.js SDK (@elephantine/sdk)

Available in sdks/typescript/:

import { ElephantineClient } from '@elephantine/sdk';

const client = new ElephantineClient('http://127.0.0.1:8765');

// Store memory
await client.remember({
  content: 'Production deployments occur on Tuesdays at 10:00 UTC.',
  category: 'devops',
  workspaceId: 'infra-team',
  roleAuthority: 0.9
});

// Recall memory
const res = await client.recall({
  query: 'deployment schedule',
  workspaceId: 'infra-team'
});
console.log(res.memories);

---

🛡️ Enterprise RBAC & Security

For multi-user teams and production deployments, Elephantine includes modular Role-Based Access Control:

• Predefined Roles:
  • admin: Full unrestricted access (read, write, delete, admin).
  • architect: Can read, write, and delete memories across all categories.
  • editor: Can read and write active memories.
  • viewer: Read-only recall access. Write and delete operations are rejected with HTTP 403 Forbidden.
• Token Authentication:
  • Enable with ELEPHANTINE_AUTH_ENABLED=true (or MEMAGENT_AUTH_ENABLED=true).
  • Authenticate requests via X-API-Key: <key> header or Authorization: Bearer <key>.
  • Default Community mode (AUTH_ENABLED=false) runs with zero configuration and zero friction.

---

📈 Benchmark & Performance

Tested on commodity Ubuntu 24.04 VDS (2 vCPU / 4 GB RAM, No GPU):

Operation	Metric	Value
Cold Start RSS Memory	Idle Memory Footprint	310 MB
Full Engine Working Set	Under Active Load	< 680 MB
Embedder Inference (CPU)	Normalized 384-dim vector	14.2 ms
Dense Vector Search	LanceDB cosine similarity	9.1 ms
Sparse BM25 Search	SQLite FTS5 index	3.2 ms
Hybrid /recall (p50)	End-to-End Latency	36.3 ms
Hybrid /recall (p95)	End-to-End Latency	42.8 ms

---

🗺️ Roadmap

• v0.1.0: Community Core MVP (LanceDB + SQLite WAL + ONNX Runtime).
• v0.1.1: Hallucination Grounding Validator & Pydantic Schema Enforcer.
• v0.1.2: Native FastMCP stdio/SSE server for Cursor & Claude Desktop.
• v0.2.0: Embedded GGUF SLM extraction (Qwen2.5-0.5B-Instruct via llama.cpp).
• v0.2.5: Graph Memory & Entity Triplet Extraction (/graph/query).
• v0.3.0: Lightweight WebUI Memory Inspector & Time-Travel Graph Visualizer.
• v0.3.5: Multi-Agent Shared Workspace & Role-Based Authority Consensus (workspace_id, role_authority).
• v0.3.8: 1-Click IDE Installers (Antigravity, Codex, Cursor, Claude, VS Code) & Cytoscape.js Interactive Graph.
• v0.4.0: TypeScript / Node.js SDK & Enterprise RBAC Security Layer.
• v1.0.0: Cross-Agent Distributed CRDT Consensus & Multi-Node Cluster Sync.

---

🤝 Contributing

We welcome contributions from systems engineers, AI researchers, and agent builders!

git clone https://github.com/partitect/elephantine.git
cd elephantine
uv venv .venv
uv pip install -e ".[dev]"
pytest -v tests/

---

🌟 Star History

---