Dexicon

Semantic search over your own files, for coding agents. One container, on your machine.

Dexicon indexes source trees, PDFs, EPUBs, Word and Markdown documents and answers questions about them over MCP, so that Claude Code and other MCP clients can search local files.

search_index("how does promotion work")      → 04-ingestion.md:228-265, and nine more
get_context("docs", "04-ingestion.md", 246)  → the passage around it, with line numbers

By default no data leaves the machine. Embeddings are generated by a local Ollama instance and stored in a local Qdrant instance. Hosted embedding providers are supported but must be configured explicitly.

---

Quickstart

Requires Docker.

git clone https://github.com/Merp4/dexicon.git && cd dexicon
cp .env.example .env
docker compose up -d

The first start downloads an embedding model of a few hundred megabytes. The admin password is printed once:

docker compose logs dexicon | grep "admin password"

Open http://127.0.0.1:8477, sign in with it, and create a corpus pointing at a directory under ./workspaces, which is mounted read-only. Set DEXICON_ADMIN_PASSWORD in .env to pin your own, or change it in the UI.

To connect an agent, issue a key under Access and tick which corpora it may reach. Leaving them all unticked means every corpus, and the ticks can be changed later without restarting the agent:

claude mcp add --transport http dexicon http://localhost:8477/mcp \
  --header "Authorization: Bearer dex_…" --scope user

docs/12 covers Cursor, VS Code, Windsurf, Cline, Claude Desktop and Zed. ./scripts/install-mcp.ps1 generates these configurations.

Connecting gives an agent the tools; it does not tell it when to reach for them. For Claude Code the same script installs a skill that does, and a hook that says what is indexed at the start of a session:

./scripts/install-mcp.ps1 -What all -WhatIf   # show the plan
./scripts/install-mcp.ps1 -What all           # skill, hooks and MCP

-Uninstall takes it back out. hooks/claude describes both hooks, including the per-prompt one that is installed but left switched off.

Features

• Hybrid retrieval. Dense and sparse vectors in a single Qdrant query with server-side fusion. If the embedding service is unavailable, search falls back to keyword matching and reports the degradation in the response.
• Document formats. PDF, EPUB, DOCX, PPTX and HTML retain their natural unit, so results cite #page=201 or #chapter=8 rather than a line number in extracted text.
• Chunk sets. A corpus may hold several chunkings, addressed as corpus:set. Changing the embedding model adds a set, backfills it, then promotes it, so search is never served from a partially built index.
• Incremental refresh. Content-hashed. A change to a chunker or extractor increments a version and reprocesses only the affected files.
• An admin password, and keys scoped to corpora. The password is the only route to administration and is never held by an agent. Each API key reaches the corpora ticked for it in the UI, re-read per request, so changing what an agent can see does not mean restarting it. Enforced at three layers.
• State reporting. A partially built index, a skipped file and an empty corpus are each distinguishable from a search that returns no results.
• An HTTP API for scripts. POST /api/context returns one assembled, cited passage within a character budget, for hooks and CI steps that have no agent loop to fetch results with. Described by its own OpenAPI document; see 13.

Status

Pre-1.0. Releases are published as ghcr.io/merp4/dexicon and described in CHANGELOG.md; the badge above shows the newest.

Default settings are derived from measurement: 81 retrieval configurations evaluated over a document corpus and again over a code corpus, recorded in benchmarks. Both corpora are drawn from this repository. The roadmap lists outstanding work.

How it fits together

┌─ your machine ────────────────────────────────────────────────┐
│                                                               │
│   Claude Code ──MCP/HTTP──┐                                   │
│   Other agents ───────────┤                                   │
│   Browser ─────HTTP───────┤                                   │
│                           ▼                                   │
│                     ┌───────────┐   ┌──────────┐              │
│                     │  dexicon  │──▶│  qdrant  │              │
│                     │ UI+API+MCP│   └──────────┘              │
│                     │ + indexer │   ┌──────────┐              │
│                     └─────┬─────┘──▶│  ollama  │              │
│                           │         └──────────┘              │
│                    /workspaces (ro)                           │
└───────────────────────────────────────────────────────────────┘

A single container runs the UI, API, MCP server and indexer, with Qdrant and Ollama alongside it. 02 explains the single-process design.

Documentation

Begin with 01 — Overview for scope and non-goals, or 12 — Connecting an agent for client configuration.

The numbered documents in docs/ cover architecture, the data model, ingestion, search, the MCP surface, authentication, the UI, deployment, security and the integration API. Decisions records design choices and the alternatives considered, benchmarks the evaluations behind the default settings, troubleshooting common problems, and the roadmap outstanding work.

Contributing

CONTRIBUTING.md covers local setup and review expectations. Security issues should be reported through SECURITY.md rather than the issue tracker.

Licence

Apache-2.0. Copyright 2026 Martyn Mcvay. Selected for its express patent grant and trademark clause; see D-14.

Every dependency is permissively licensed across the whole transitive tree. See the review, and scripts/licence-review.py to re-run it.