SocratiCode: a local, Docker-managed codebase context engine for AI assistants

The problem SocratiCode targets: assistants that read code by grepping

An AI assistant asked a question about a large repository usually answers by searching for strings. That works on a small project and degrades badly on a large one, because the assistant cannot hold the dependency structure in context. SocratiCode's README frames the project as a context engine that pre-computes the hard parts, so the model receives ranked code fragments, blast radius and call-flow instead of raw file listings. The README also states that its benchmark on VS Code (2.45M lines) showed 61% less context, 84% fewer tool calls and 37x faster exploration than grep-based approaches, tested with Claude Opus 4.6.

The intended user is a developer or team already using an MCP host (Claude Code, VS Code, Cursor, Gemini CLI) on a repository large enough that naive search wastes tokens. The project claims testing on repositories up to roughly 40 million lines of code. It is not a linter, a code review bot or an editor. It is an index and a query surface.

How the index is built: Docker, Qdrant and Ollama

The repository ships a docker-compose.yml with two services. Qdrant runs as qdrant/qdrant:v1.17.0, exposed on host port 16333 for HTTP and 16334 for gRPC, with a named volume socraticode_qdrant_data for storage. Ollama runs as ollama/ollama:latest on host port 11435, with socraticode_ollama_data for model weights. Both use restart: unless-stopped. The README states Docker handles everything and that no API keys are required, so embeddings are generated locally by default.

On top of that, the TypeScript server walks the repository, chunks files with AST awareness, embeds the chunks, and writes vectors plus payloads into Qdrant. Search is hybrid: semantic vector search fused with BM25 through reciprocal rank fusion. Alongside the vectors, the indexer builds a polyglot dependency graph, which is what enables symbol-level impact analysis and call-flow tracing. The README claims coverage for 18 languages.

Two operational details matter. Indexing is batched and resumable, so an interrupted run continues from a checkpoint rather than restarting. A file watcher updates the index on change. Both are documented in the README; neither is something you configure.

Installing SocratiCode and running a first search

The package is published to npm as socraticode and requires Node.js >= 18.17. The README's simplest path for an MCP host is to let npx fetch it, which is also the configuration encoded in the VS Code and Cursor install badges. The MCP entry looks like this:

{
  "mcpServers": {
    "socraticode": {
      "command": "npx",
      "args": ["-y", "--prefer-online", "socraticode@latest"]
    }
  }
}

Adding that to your host's MCP configuration and restarting the host should surface SocratiCode's tools. The first index of a large repository is the slow part; the README says indexing is batched and resumable, so if it is interrupted, run it again rather than clearing state.

The two backing services come from the compose file in the repository. From a clone of the repo:

docker compose up -d

That starts Qdrant on 16333/16334 and Ollama on 11435. If you prefer to run the server directly rather than through npx, the package exposes a bin named socraticode pointing at dist/index.js, and the repository's own scripts include npm run build and npm start.

For Claude Code users the README recommends the plugin path instead. The repository contains .claude-plugin/, skills/, agents/ and hooks/, and the README points at a Claude Code plugin install badge. The exact install command is in the README's Quick Start section, which the excerpt here does not include, so follow it there rather than guessing.

Where SocratiCode is the wrong tool

Docker is a hard dependency for the default local setup. The compose file defines Qdrant and Ollama as containers, and the README describes Docker as handling everything. On a machine where developers cannot run Docker (locked-down corporate images, some CI runners, restricted macOS or Windows environments), the zero-configuration promise does not hold, and the README does not document a fallback for that case.

Embedding a very large repository is also a resource commitment. The README states testing at roughly 40 million lines, but it does not publish index build times or memory ceilings per repository size. Treat the first index of a monorepo as a batch job you schedule, not something that finishes while you wait.

The licence is the third constraint. package.json declares "license": "AGPL-3.0-only", and the repository carries both LICENSE and LICENSE-COMMERCIAL. If your product links to or ships AGPL-3.0 code, the network-copyleft terms may not fit how you distribute. The repository's own answer to that is the commercial licence file; read it rather than assuming the open-source terms cover your case.

Finally, a shared team index is not part of the open-source core. The README describes SocratiCode Cloud as a private beta offering a hosted, shared team index with SSO, audit logs and VPC or air-gapped deployment. Branch-aware indexing is listed among the cloud features, so do not assume the open-source server gives you a centrally managed multi-user index out of the box.

SocratiCode compared with plain vector search and with grep-based MCP tools

The obvious alternative is a generic vector store plus an embedding pipeline that you assemble yourself: chunk files, embed them, push to Qdrant or another store, expose a search tool to your assistant. That gives you full control over chunking and metadata, and it works with any language you can write a parser for. The cost is that you own the chunker, the watcher, the resumable indexing logic and the ranking. SocratiCode's difference is that it bundles AST-aware chunking, hybrid BM25 plus vector retrieval fused with RRF, and a dependency graph in one server, with the backing services defined in docker-compose.yml.

The second alternative is the class of tools that answer code questions by running text search and returning file excerpts. Those need no index at all and work on any repository instantly. SocratiCode's bet is that pre-computing structure pays off on large codebases: the README's benchmark claim is precisely about fewer tool calls and less context versus grep-based exploration. On a small repository that bet does not pay, because the index build costs more than the searches it saves.

A third comparison the README itself makes is with cloud embedding providers. SocratiCode supports OpenAI and Google Gemini embeddings and Qdrant as configuration options, but defaults to local. If you already have a hosted embedding pipeline and are comfortable with code leaving your network, the local default is a constraint rather than a feature.

Licence, maintenance and upgrade cost

The last push to the repository was on 2026-09-10, and the most recent releases are v1.13.2 (2026-09-09), v1.13.1 (2026-09-07) and v1.13.0 (2026-09-07). package.json lists version 1.13.3, which is ahead of the newest tagged release in the repository, so expect the npm package and the GitHub releases to move independently. The repository is not archived.

Upgrades are the usual npm story. The MCP configuration shown in the README pins socraticode@latest, which means every host restart can pick up a new version; if you want reproducibility, pin an exact version instead. The compose file also pins qdrant/qdrant:v1.17.0 but uses ollama/ollama:latest, so the Ollama container will drift on pull. That asymmetry is worth knowing before you debug a search-quality change.

On licensing: AGPL-3.0-only is declared in package.json, and the repository ships a separate LICENSE-COMMERCIAL alongside it. Whether your use requires the commercial licence is a legal question, not one this article can answer. The practical step is to read both files in the repository and, if your organisation distributes software, involve whoever handles licence compliance.

Editorial conclusion

Adopt SocratiCode if your team already runs an MCP-capable assistant and wants semantic code search without sending source to a third party; the Docker Compose file keeps Qdrant and Ollama on your machine. Skip it if you cannot run Docker on developer machines, if you need a hosted shared index today (that is the private beta at socraticode.cloud), or if AGPL-3.0 is incompatible with how you distribute your product. Before rolling it out, verify the first index on your largest repository completes, check that the Ollama embedding model is pulled, and read LICENSE-COMMERCIAL to see whether your use falls under the commercial terms.

Frequently asked questions

Official sources

1. giancarloerra/SocratiCode on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases