-
Notifications
You must be signed in to change notification settings - Fork 0
Installation
This guide covers all installation methods for NeuralMind, including system requirements, dependencies, and platform-specific instructions.
NeuralMind is a local, offline Python package — no SaaS, no accounts, no outbound calls. Once installed, it works from the CLI, via its MCP server, and (for Claude Code) as a PostToolUse compression layer. See the Setup Guide for post-install configuration or Use Cases to pick a workflow first.
- Install — pick your path (new in v0.7.0)
- System Requirements
- Quick Install
- Installation Methods
- Dependencies
- Platform-Specific Instructions
- Verification
- Troubleshooting
New in v0.7.0. NeuralMind installs five ways. All paths deliver the same package — the neuralmind CLI, the neuralmind-mcp server, and the Python module.
| Method | Command | When to pick |
|---|---|---|
| pip | pip install neuralmind graphifyy |
Default. Drops it in your active env. |
| pipx | pipx install neuralmind && pipx inject neuralmind graphifyy |
Global CLI, no env pollution. |
| uv | uv pip install neuralmind graphifyy |
Modern, fast Python tooling. |
| Docker | docker pull ghcr.io/dfrostar/neuralmind:latest && docker run --rm -v "$PWD:/project:ro" ghcr.io/dfrostar/neuralmind:latest neuralmind --help |
Containerized — no Python on the host. Multi-platform (linux/amd64 + linux/arm64); auto-published to GHCR on every release since v0.9.0. |
| From source | git clone https://github.com/dfrostar/neuralmind && pip install -e . |
Hacking on NeuralMind itself. |
Verify any install:
neuralmind --help # works for every path
# For pip / uv / source (a Python env where neuralmind is importable):
python -c "import neuralmind; print(neuralmind.__version__)"Full walkthrough with pros and cons of each path: Install paths.
The sections below remain the deep reference — system requirements, dependency tables, platform-specific notes, and troubleshooting.
| Component | Requirement |
|---|---|
| Python | 3.10 or higher |
| Memory | 2GB RAM (4GB+ recommended for large codebases) |
| Storage | 500MB for base install + space for embeddings |
| OS | Linux, macOS, Windows 10+ |
- Python 3.10+: Download from python.org
- pip (or pipx / uv): Usually included with Python
- git (optional): For source installation
- graphify: For generating knowledge graphs from codebases (installed alongside NeuralMind in every path above)
For most users, the quickest path:
# Install NeuralMind
pip install neuralmind
# Install graphify for knowledge graph generation
pip install graphifyy
# Verify installation
neuralmind --helpPrefer one of the other four install paths? See the install matrix above.
The default installation method.
pip install neuralmindThis includes everything most users need: the CLI, the semantic
indexing layer, and the MCP server (neuralmind-mcp) for Claude
Desktop, Claude Code, Cursor, Cline, Continue, Hermes-Agent,
OpenClaw, and any other MCP-compatible client.
Note for users upgrading from v0.4.x or earlier: the MCP server used to be gated behind an
[mcp]extra. From v0.5.0 onward it ships in the base package. Existingpip install "neuralmind[mcp]"commands still work — themcpextra is preserved as an empty no-op for backwards compatibility.
For contributors or those who want testing/linting tools:
pip install neuralmind[dev]All extras (equivalent to [dev] since v0.5.0):
pip install neuralmind[all]pipx installs each Python application in its own dedicated venv and exposes the entry points on your PATH globally. neuralmind and neuralmind-mcp are then available from any directory without activating anything.
pipx install neuralmind
pipx inject neuralmind graphifyyTrade-off: because pipx isolates the package, import neuralmind from your project's own Python won't work. If you also script against the Python API, use pip in a project venv instead.
uv is Astral's Rust-based Python package manager — significantly faster installs, drop-in for pip, compatible venvs.
uv pip install neuralmind graphifyyFor a uv-managed project:
uv add neuralmind graphifyyPull from GHCR (auto-published since v0.9.0, multi-platform linux/amd64 + linux/arm64):
docker pull ghcr.io/dfrostar/neuralmind:latest
# or pin a specific version
docker pull ghcr.io/dfrostar/neuralmind:v0.9.0
# Run the MCP server. `neuralmind-mcp` ignores any CLI args; each MCP
# tool call (neuralmind_wakeup, neuralmind_query, …) carries its own
# `project_path` argument that the client passes in. The mount below
# just exposes the project tree so those tool calls can find the path.
docker run --rm -i \
-v "$PWD:/project:ro" \
ghcr.io/dfrostar/neuralmind:latest neuralmind-mcp
# Run the graph view on http://localhost:8765
docker run --rm -p 8765:8765 \
-v "$PWD:/project:ro" \
ghcr.io/dfrostar/neuralmind:latest \
neuralmind serve /project --host 0.0.0.0 --no-authLocal build — if you want to build the image yourself from the repo's
Dockerfile:docker build -t neuralmind:dev .then substituteneuralmind:devforghcr.io/dfrostar/neuralmind:latestin the commands above.
To persist the index between runs, mount the project directory read-write so .neuralmind/ and graphify-out/ land on the host:
docker run --rm -v "$PWD:/project" ghcr.io/dfrostar/neuralmind:latest neuralmind build /projectFor the latest development version or contributors:
# Clone the repository
git clone https://github.com/dfrostar/neuralmind.git
cd neuralmind
# Install in editable mode
pip install -e .
# Or with dev tools
pip install -e ".[dev]"Recommended setup for contributors:
# Clone and enter directory
git clone https://github.com/dfrostar/neuralmind.git
cd neuralmind
# Create virtual environment
python -m venv venv
source venv/bin/activate # Linux/macOS
# or: venv\Scripts\activate # Windows
# Install with dev dependencies
pip install -e ".[dev]"
# Install pre-commit hooks (optional)
pre-commit install| Package | Version | Purpose |
|---|---|---|
| chromadb | ≥0.4.0 | Vector database for embeddings |
| pyyaml | ≥6.0 | Configuration file parsing |
| toml | ≥0.10 | TOML configuration file support |
| mcp | ≥1.23.0 | Model Context Protocol server (since v0.5.0) |
| Package | Version | Purpose |
|---|---|---|
| pytest | ≥7.0 | Testing framework |
| pytest-asyncio | ≥0.21.0 | Async test support |
| black | ≥23.0 | Code formatting |
| ruff | ≥0.1.0 | Fast linting |
pip install "neuralmind[mcp]" still resolves cleanly — the extra
is preserved as an empty no-op so existing install commands in user
docs, blog posts, and CI configs keep working. No reason to use it
in new commands; pip install neuralmind already includes the MCP
server.
| Tool | Installation | Purpose |
|---|---|---|
| graphify | pip install graphifyy |
Knowledge graph generation |
# Ensure Python 3.10+ is installed
sudo apt update
sudo apt install python3.10 python3.10-venv python3-pip
# Create virtual environment (recommended)
python3.10 -m venv neuralmind-env
source neuralmind-env/bin/activate
# Install NeuralMind
pip install neuralmind# Using Homebrew
brew install python@3.11
# Create virtual environment
python3.11 -m venv neuralmind-env
source neuralmind-env/bin/activate
# Install NeuralMind
pip install neuralmind# Ensure Python 3.10+ is installed from python.org
# Open PowerShell as Administrator
# Create virtual environment
python -m venv neuralmind-env
.\neuralmind-env\Scripts\Activate.ps1
# Install NeuralMind
pip install neuralmindUse the repo's Dockerfile — multi-stage, non-root, transitive deps pre-wheeled in the builder stage so the runtime image doesn't need a C toolchain. See the Docker section above for the build and run commands, or the install-paths walkthrough for persistence and security notes.
If you want a minimal app-style Dockerfile for embedding NeuralMind inside another image:
FROM python:3.12-slim
WORKDIR /app
# Install NeuralMind (MCP server is bundled by default) + graph builder
RUN pip install --no-cache-dir neuralmind graphifyy
# Your project files
COPY . .
CMD ["neuralmind-mcp"]# Check CLI is available — works for every install path
neuralmind --help
# Check version — pip / uv / source paths only
# (pipx isolates the package in its own venv; Docker runs in-container)
python -c "import neuralmind; print(neuralmind.__version__)"# Check ChromaDB
python -c "import chromadb; print(f'ChromaDB version: {chromadb.__version__}')"
# Check graphify (if installed)
graphify --help# Create a test directory
mkdir test-neuralmind
cd test-neuralmind
# Create a simple Python file
echo 'def hello(): return "world"' > hello.py
# Generate knowledge graph (requires graphify)
graphify update .
# Build neural index
neuralmind build .
# Test query
neuralmind wakeup .Cause: Python scripts directory not in PATH.
Solution:
# Linux/macOS
export PATH="$HOME/.local/bin:$PATH"
# Then retry
neuralmind --helpCause: Dependencies not installed properly.
Solution:
pip install --upgrade neuralmind
# or
pip install chromadb>=0.4.0Cause: Knowledge graph not generated.
Solution:
# Install graphify if not present
pip install graphifyy
# Generate knowledge graph
graphify update /path/to/your/project
# Then build neural index
neuralmind build /path/to/your/projectCause: Insufficient RAM for embedding generation.
Solution:
- Close other applications
- Process in batches using
--forceflag to rebuild incrementally - Consider using a machine with more RAM
Cause: Corporate proxy or certificate issues.
Solution:
pip install --trusted-host pypi.org --trusted-host pypi.python.org neuralmind- GitHub Issues: Report bugs
- Discussions: Ask questions
After installation:
- Generate a knowledge graph for your project
-
Build the neural index using
neuralmind build - Query your codebase with natural language
- Set up MCP integration for Claude Desktop