SocratiCode

What it does

SocratiCode builds a searchable index of a codebase on your own machine and exposes it to an assistant over stdio. It splits source files into chunks along their syntax tree, embeds them, and stores them in a Qdrant vector database, so a query runs both a meaning-based search and a BM25 keyword search and merges the two result lists. Indexing runs in the background in batches with checkpoints, so an interrupted run picks up where it stopped, and a file watcher (or, optionally, a refresh on git branch changes) keeps the index current.

On top of the search index it builds two graphs. The first maps which files import which, finds circular dependencies and can draw the result as a Mermaid diagram or a standalone HTML page that opens in the browser. The second maps which functions call which, so the assistant can ask what would be affected by changing a symbol, trace execution forward from an entry point, or list a symbol's callers and callees. Full support covers about twenty languages, including TypeScript, Python, Java, Go, Rust, C#, PHP and Swift; other text formats are indexed for search only.

It can also index 'context artifacts' you list in a .socraticodecontextartifacts.json file, such as database schemas, API specs or infrastructure configs, and search them alongside the code. Several projects can be linked for cross-project search, and git worktrees or branches can share or separate an index.

By default it starts its own Qdrant container and uses Ollama for embeddings, so nothing leaves the machine. OpenAI, Google Gemini, LM Studio or a LiteLLM proxy can be used for embeddings instead, and an external or Qdrant Cloud instance can replace the local database. Besides the plain MCP server, its makers ship plugins for Claude Code, OpenAI Codex, VS Code and Cursor that bundle the same engine. A hosted team version, SocratiCode Cloud, is in private beta and separate from this server.

What it needs

Node.js 18.17 or newer with npx on the PATH, and an MCP host that runs local stdio servers. In the default setup Docker must be running: it hosts the managed Qdrant database and, unless a native Ollama install is found, the Ollama embedding container. First start downloads the images and an embedding model (around five minutes). Docker is optional only with an external Qdrant plus native Ollama or a cloud embedding provider, which then needs its own API key. On Alpine Linux ARM64, run apk add --no-cache gcompat first so the bundled Swift parser can load.

Limits

• Not covered The call graph is static analysis without type inference. Calls through dynamic dispatch, reflection, eval, macros or dependency injection are missed
• Platform Docker on macOS and Windows has no GPU access, so the default Ollama container is slow on larger repositories. Native Ollama or OpenAI is suggested there
• Size cap Files over 5 MB are skipped by default, changeable with MAX_FILE_SIZE_MB
• Limit A new embedding provider or model only applies after the existing index is removed and rebuilt
• Limit External Qdrant must be v1.15.2 or later for hybrid search
• Limit With OLLAMA_API_KEY set, plain http is refused unless the host is loopback, and a URL with credentials in it is refused (src/services/provider-ollama.ts)
• Rate limit Opens at most 4 connections to Ollama at once by default, set by OLLAMA_MAX_CONNECTIONS, a setting the README does not list (src/services/embedding-config.ts)

The call graph comes from static analysis with no type inference: calls made through dynamic dispatch, reflection, eval, macros or framework dependency injection do not show up, so 'zero callers' can be wrong on DI-heavy code. Docker on macOS and Windows has no GPU access, so the default embedding container is slow on medium or large repositories; its makers suggest native Ollama or OpenAI embeddings there. Files over 5 MB are skipped by default. Changing the embedding provider or model does not apply to an existing index until it is removed and rebuilt. External Qdrant must be v1.15.2 or later for hybrid search.

Who it suits

Suits developers working on large or many-language repositories who want an assistant to search by meaning and check the impact of a change before refactoring, while keeping code on their own machine. It is a heavier install than grep-style tools: it needs Docker or an external Qdrant and an embedding model, plus an initial indexing pass. For small repositories or lookups of exact names, its own docs say plain grep can be as good. Teams wanting a shared, hosted index would look at the makers' separate SocratiCode Cloud instead. It is a community project, not tied to any vendor, and its AGPL-3.0 licence matters if you modify it and offer it as a network service.