Open Index

Open Index is an open-source tool built by DrDroidLab for constructing domain-specific, structured context graphs — called "brains" — that AI agents can search, read, and update through an MCP server. Released under the MIT License, it is written in Python and available on GitHub. The project targets the gap between demo-quality agents and production agents that drift, stall, or act on stale context.

What It Is

Open Index is a context-layer engine for domain-specialized AI agents. Rather than feeding agents raw documents or unstructured retrieval results, it lets you define a typed, relational knowledge graph — a "brain" — and expose it to agents over the Model Context Protocol (MCP). The brain is domain-agnostic: you can model infrastructure (service → runbook), a sales pipeline (customer → order), a support org (product → issue), or any other domain by defining your own concepts and edges. Open Index stores, searches, and maps those concepts, and gives agents a validated path to both consume and maintain that knowledge.

Four Primitives

Every brain is built from four building blocks:

• doc_type — a concept to track (e.g. service, customer, issue), defined as a YAML schema with typed fields, per-field search weights (boost), and optional relationship declarations.
• doc_schema — the fields stored for a given doc_type, with data types (string, text, number, timestamp) and search kinds (syntactic, semantic, none).
• entity — one instance of a doc_type, stored as JSON. Every entity can link to others via related_to + relationship_edge_meaning, forming a graph without requiring a graph database.
• connector — an optional ingestion script that pulls entities from an MCP server on a schedule, enabling continuously-updated, connector-pulled data.

MCP Integration and Agent Workflow

The MCP server (open-index mcp) is the primary interface between a brain and an agent. It exposes read and write tools over stdio or HTTP:

• Read: navigation_guidelines() injects domain-specific navigation instructions into the agent prompt; search_brain() and get_entity() retrieve context.
• Write: put_entity(), put_entities(), and create_doc_type() let agents add or update knowledge, enabling self-learning loops where agents write back what they discover.
• Read-only mode: --read-only restricts agents to retrieval only, suitable for query-only endpoints.

The server also supports multi-brain deployments (open-index serve --brains <root>), serving every brain under a directory from one process, each at /<name>/mcp.

Storage and Search Backends

Open Index defaults to SQLite + FTS5 — zero external services, suitable for local development and brains up to roughly 10,000 entities. For larger or multi-writer deployments, it supports OpenSearch, which adds native per-field boosting, fuzzy (typo-tolerant) search, and k-NN semantic search. The backend is selected via brain.yaml or environment variables, so the same brain definition works in both environments.

Semantic search is enabled by installing the [semantic] extra, which defaults to the BAAI/bge-small-en-v1.5 (384-D) local embedding model. An OpenAI-compatible embedding API can be substituted via environment variables.

Explorer UI and Analytics

open-index ui launches a local read-only explorer with four tabs: Explore (search and browse entities and their relationships), Map (auto-anchored graph visualization of the most-connected entities), Analytics (fetch counts by client/operation, zero-result searches, latency, and recent activity — stored locally and never sent externally), and Jobs (connector schedules and status). Analytics data lives in ~/.local/state/open-index/ and is not transmitted to the project's creators.

Deployment and Production Path

For shared or cloud deployments, open-index serve exposes the MCP context layer over streamable HTTP with bearer-token authentication. Docker Compose profiles (sqlite, opensearch, ui) are provided for containerized setups. The open-index mcp-config command prints the exact connection block to paste into Claude Code, Claude Desktop, Cursor, or any MCP-compatible agent host. A portable SKILL.md in skills/setup-open-index/ follows the agent skills format used by runtimes including OpenClaw, Hermes, and Claude Code, allowing agents to set up Open Index themselves.

Current Status

The repository was created in August 2026 and last pushed in mid-August 2026, indicating early active development. It carries 35 GitHub stars and 2 forks at the time of indexing, with zero open issues. The project is MIT-licensed and accepts community contributions via GitHub and Discord.