⚡ AlekhDB: Local-First Cognitive GraphRAG Database & MCP Server

WebPage : https://alekhdb.lovable.app/

The Light-Speed, Local-First Cognitive Memory Engine, structured Action Replay Tracer, and Model Context Protocol (MCP) Server for Autonomous AI Agents.

---

AlekhDB (meaning "graph, record, drawing" in Sanskrit) is a high-performance, lightweight GraphRAG Database & Cognitive Memory Engine built specifically for developers orchestrating autonomous AI agents.

Traditional vector databases store flat, append-only embeddings lists. They suffer from Context Rot, lack Relational Topology, and have Zero Cognitive Capabilities to handle logical contradictions. AlekhDB engineers a biological, self-editing AI memory layer equipped with exponential Ebbinghaus attention curves, Doyle-style truth maintenance systems (TMS), AST-aware codebase mapping, chronological action tracing, and a zero-dependency virtual POSIX filesystem mount.

---

---

🚀 How it Works (in 60 Seconds)

• 📥 Ingest & Extract: Ingest raw text or codebase structures. AlekhDB parses them into a high-speed local knowledge graph of entities and semantic relationships in under 1 ms.
• 🧠 Audit & Align: A Doyle-style Truth Maintenance System (TMS) instantly monitors incoming facts against active beliefs, soft-decaying conflicting historical edges (down to weight 0.15) instead of destroying them to preserve chronological context.
• 📈 Decay & Search: Exponential Ebbinghaus relevance curves archive low-strength faded nodes to keep active token windows hyper-dense, while Spaced Repetition instantly resurrects them during GraphRAG queries.

---

⚖️ Why AlekhDB? (Architectural Comparison)

When compared to standard vector stores or simple flat-file memory buffers, AlekhDB represents a massive leap in cognitive retrieval and agentic utility:

Feature / Capability	Chroma	Pinecone	Mem0	⚡ AlekhDB
Attention Curves	❌ No	❌ No	❌ No	🟢 Yes (Ebbinghaus Decay)
Contradiction Detection	❌ No	❌ No	❌ No	🟢 Yes (Doyle TMS)
MCP Server for Claude/Cursor	❌ No	❌ No	❌ No	🟢 Yes (Cursor/Claude Native)
POSIX Filesystem Mount	❌ No	❌ No	❌ No	🟢 Yes (Shell Simulator)
AST-Aware Code Memory	❌ No	❌ No	❌ No	🟢 Yes (Class/Method Parser)
Sub-Millisecond Query Latency	⚠️ Slow	⚠️ Network	⚠️ Heavy	🟢 Fast (<0.50ms core loop)
Zero Compile Setup	❌ Heavy	❌ Cloud	⚠️ Compile	🟢 Yes (Zero compile/dependencies)

---

🧠 The Taxonomy of Memories

AlekhDB categorizes knowledge into six distinct memory tiers, mimicking human cognitive storage and computational requirements:

• 🌐 Semantic Memory (Ontological Graph): Entities (Nodes) connected by Weighted Relationships (Edges). Subject to Ebbinghaus decay and spaced repetition boost.
• 🎬 Episodic Memory (Execution Traces): Chronological trace frames housing ordered event steps (tools, inputs, results, errors). Compacts into Semantic Memory upon completion.
• ⚡ Working Memory (Active Context): A filtered subset of nodes/edges that fits inside the current query to minimize token load.
• 🗄️ Subconscious Memory (Decayed / Archived): Nodes with cognitiveStrength < 0.15 that reside out of active context search but are instantly revived via Spaced Repetition if queried.
• 💻 Procedural Code Memory (AST Graph): Hierarchies of File, Class, and Function nodes mapped natively. Permanently locked (exempt from Ebbinghaus decay).
• 📂 Virtual Memory (POSIX Mount): Graph states mapped into virtual file folders (e.g. /memory/profile.md). Readable via standard CLI bash tools.

---

⚡ Core Cognitive Senses

• Ebbinghaus Relevance Decay: Memory relevance recedes exponentially over time ($S_t = S_0 e^{-\lambda \Delta t}$) to prevent active context rot. Faded nodes automatically archive if strength drops below 0.15.
• Spaced Repetition Reinforcement: Accessing, querying, or searching a node boosts its cognitive strength by $+0.35$ (capped at 2.0) and resets its decay timer.
• Doyle-Style Truth Maintenance System (TMS): Automatically audits incoming facts against the active graph to calculate a Cognitive Dissonance Score. If a contradiction is detected (e.g., stack migrations), conflicting historical edges are soft-decayed (reduced to weight 0.15) rather than deleted, maintaining chronological timeline context.
• Context-Change-1 Self-Editing: Prompts active LLMs to evaluate redundancies and prune context chunks dynamically on ingestion to weed out "context rot".
• POSIX Mounted Directory: Projects memory states into a virtual local filesystem mount. AI agents can explore memories using standard ls and cat commands inside their terminal.

---

📈 Latency & Performance Scorecard

AlekhDB core is designed to be completely lightweight, zero-dependency, and incredibly fast. The following benchmark scores are verified locally on a standard Node.js zsh shell:

Operations	Latency	Target Limit	Status
10K Async ID Collision	6.14 ms	< 50 ms	0% Collisions ✔
Graph Seeding	0.54 ms	< 10 ms	Lightweight Core ✔
Fact Ingestion & TMS	0.54 ms	< 300 ms	Sub-millisecond ✔
Deep GraphRAG Search	0.45 ms	< 100 ms	Sub-millisecond ✔
AST Codebase Parsing	0.88 ms	< 150 ms	Flawless ESM Scanner ✔

---

🛠️ Installation & Quick Start

🚀 The 5-Second Instant Quickstart (Copy & Paste):

git clone https://github.com/trident/alekhdb.git && cd alekhdb && npm install && npm run doctor && npm test

1. Seed Database

Preload codebase components, B2B sales pipelines, and legal mock nodes:

node cli.js seed

2. Configure Context Capacity

Adjust the active context window token capacity limit dynamically in zsh (supporting limits from 8,000 to 1,000,000 tokens):

# View active context capacity limits
node cli.js capacity

# Resize context capacity limit to 1,000,000 tokens
node cli.js capacity 1000000

3. Ingest Facts & Audit Contradictions

# Add a fact (automatically registers contradiction TMS audits)
node cli.js add "Trident switched backend preferences to Bun.sh runtime"

# Search memory using GraphRAG
node cli.js grep "Bun runtime"

---

🤖 Model Context Protocol (MCP) Server

AI Agents (such as Claude Code, Claude Desktop, and Cursor) can connect natively to AlekhDB using the Model Context Protocol (MCP) JSON-RPC server. This allows agents to seamlessly search, add, and query their cognitive memory layers directly during code generation passes.

Connecting to Claude Desktop

Add this to your Claude Desktop configuration file (typically at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "alekhdb": {
      "command": "node",
      "args": ["/absolute/path/to/alekhdb/mcp_server.js"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

Exported MCP Tools

Once mounted, the agent automatically acquires three core cognitive memory tools:

• 🟢 alekhdb_add: Ingest a new text statement or website scraper memory into the database.
• 🟢 alekhdb_search: Query graph memory via hybrid vector GraphRAG sweeps + 2-degree neighborhood traversals.
• 🟢 alekhdb_profile: Instantly retrieve live-synthesized Markdown developer profile outlining stable preferences.

---

🌐 OpenAPI 3.0 REST API Gateway

Start the API Gateway server:

npm run api

This launches a high-performance Express REST gateway on http://localhost:3000. AI agents and external scripts can communicate with AlekhDB using these standardized endpoints:

• Ingest Fact Node (POST /api/ingest):

  { "text": "Trident migrated project stack to Bun.sh", "scope": "work" }

• Hybrid GraphRAG Search (POST /api/search):

  { "query": "What backend runtime does Trident use?", "scope": "all" }

• Developer Profile Synthesis (GET /api/profile): Returns live-synthesized developer profile Markdown.

---

📜 License

AlekhDB is open-source software licensed under the MIT License.