Almanac

A lightning-fast data access platform for AI Agents that leverages graph-enhanced retrieval (LightRAG) to make any data source instantly accessible.

Follow us: X/Twitter • LinkedIn

🚀 Quick Start

# Clone and install
git clone https://github.com/tryprotege/almanac.git
cd almanac
pnpm install

# Start everything (one command)
pnpm start

Open http://localhost:5173 to access the UI.

First-time setup:

1. You'll see a setup wizard if configuration is missing
2. Enter your LLM API key and settings via the UI
3. Click "Save Configuration" and restart

📚 Documentation

Comprehensive guides and tutorials are available in the docs directory:

Getting Started

• Installation Guide - Local development and Docker setup
• Quick Start - Your first query in 5 minutes
• Configuration - LLM models, API keys, and settings
• AI Clients - Connect Claude Desktop, Cline, ChatGPT

Core Concepts

• LightRAG Algorithm - Understanding the 5 query modes
• System Architecture - How Almanac works under the hood

Data Sources

• Custom MCP Servers - Build your own integrations
• Data Syncing - How data flows through Almanac

Query & Search

• API Reference - REST API endpoints and parameters
• Best Practices - Optimize your queries
• Query Examples - See all query modes in action

🎯 What Makes Almanac Different

• 🚀 10x Faster - Entity-based retrieval reduces tokens while improving accuracy
• 🔌 Zero Config - Automatically generates indexing for any MCP server
• 🧠 Smart Retrieval - 5 query modes (naive, local, global, hybrid, mix) adapt to your needs
• 📊 Graph-Enhanced - Understands relationships between entities, not just keywords
• ⚡ Production Ready - Parallel processing, multi-database architecture, built to scale

📦 Architecture

External APIs → MCP Servers → Almanac
                                ↓
                    [Syncing & Indexing]
                                ↓
                    ┌─────────────────────┐
                    │     Databases       │
                    │  - MongoDB (docs)   │
                    │  - Qdrant (vectors) │
                    │  - Memgraph (graph) │
                    │  - Redis (cache)    │
                    └─────────────────────┘
                                ↓
                    [LightRAG Query Engine]
                                ↓
                            Results

Monorepo Structure

almanac/
├── packages/
│   ├── client/          # React + Vite frontend
│   ├── server/          # Express.js backend
│   ├── shared-util/     # Shared utilities
│   ├── indexing-engine/ # LightRAG implementation
│   └── benchmark/       # Performance testing
├── docs/                # Full documentation
└── docker-compose.yml   # Infrastructure services

🗄️ Infrastructure Services