Vector search, embeddings, and ML primitives in PostgreSQL, with optional services for agents, MCP, and a desktop UI.

Get vector search working in under a minute:

# 1. Start PostgreSQL with NeuronDB
docker compose up -d neurondb

# 2. Connect and create extension
psql "postgresql://neurondb:neurondb@localhost:5433/neurondb" -c "CREATE EXTENSION IF NOT EXISTS neurondb;"

# 3. Create table, insert vectors, create index, and search
psql "postgresql://neurondb:neurondb@localhost:5433/neurondb" <<EOF
CREATE TABLE documents (
  id SERIAL PRIMARY KEY,
  content TEXT,
  embedding vector(384)
);

INSERT INTO documents (content, embedding) VALUES
  ('Machine learning algorithms', '[0.1,0.2,0.3]'::vector),
  ('Neural networks and deep learning', '[0.2,0.3,0.4]'::vector),
  ('Natural language processing', '[0.3,0.4,0.5]'::vector);

CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops);

SELECT id, content, embedding <=> '[0.15,0.25,0.35]'::vector AS distance
FROM documents
ORDER BY embedding <=> '[0.15,0.25,0.35]'::vector
LIMIT 3;
EOF

[!SECURITY] The default password (neurondb) is for development only. Always change it in production by setting POSTGRES_PASSWORD in your .env file. See Service URLs & ports for connection details.

• What you can build
• Architecture
• Installation
  • Quick start (Docker)
  • Native install
  • Minimal mode (extension only)
• Service URLs & ports
• Documentation
• Repo layout
• Benchmarks
• GPU profiles (CUDA / ROCm / Metal)
• Contributing / security / license
• Project statistics

• Semantic & hybrid search: vector similarity + SQL filters + full-text search
• RAG pipelines: store, retrieve, and serve context with Postgres-native primitives
• Agent backends: durable memory and tool execution backed by PostgreSQL
• MCP integrations: MCP clients connecting to NeuronDB via tools/resources

flowchart LR
  subgraph DB["NeuronDB PostgreSQL"]
    EXT["NeuronDB extension"]
  end
  AG["NeuronAgent"] -->|SQL| DB
  MCP["NeuronMCP"] -->|tools/resources| DB
  UI["NeuronDesktop UI"] --> API["NeuronDesktop API"]
  API -->|SQL| DB

Choose what you need:

Option 1: Use published images (recommended)

Pull pre-built images from GitHub Container Registry:

# Pull latest images
docker compose pull

# Start services
docker compose up -d
./scripts/health-check.sh

Option 2: Build from source

docker compose up -d --build
./scripts/health-check.sh

[!SECURITY] Default credentials are for development only. In production, set strong passwords via environment variables or .env file.

Install the NeuronDB extension directly into your existing PostgreSQL installation.

cd NeuronDB
make
sudo make install

CREATE EXTENSION neurondb;

shared_preload_libraries = 'neurondb'

sudo systemctl restart postgresql

# Vector index settings
neurondb.hnsw_ef_search = 40          # HNSW search quality
neurondb.enable_seqscan = on          # Allow sequential scans

# Memory settings
neurondb.maintenance_work_mem = 256MB # Index build memory

-- Check current version
SELECT extversion FROM pg_extension WHERE extname = 'neurondb';

-- Upgrade to latest
ALTER EXTENSION neurondb UPDATE;

For detailed installation instructions, see NeuronDB/INSTALL.md.

Use NeuronDB as a PostgreSQL extension only, without the Agent, MCP, or Desktop services.

Benefits:

• ✅ No extra services or ports
• ✅ Minimal resource footprint
• ✅ Full vector search, ML algorithms, and embeddings
• ✅ Works with any PostgreSQL client

Installation:

Follow the Native install steps above. That's it! You now have vector search and ML capabilities in PostgreSQL.

Usage:

-- Create a table with vectors
CREATE TABLE documents (
  id SERIAL PRIMARY KEY,
  content TEXT,
  embedding VECTOR(1536)
);

-- Create HNSW index
CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops);

-- Vector similarity search
SELECT id, content
FROM documents
ORDER BY embedding <=> '[0.1, 0.2, ...]'::vector
LIMIT 10;

No additional services, ports, or configuration required!

• Start here: DOCUMENTATION.md (documentation index)
• Beginner walkthrough: Docs/getting-started/simple-start.md
• Technical quick start: QUICKSTART.md
• Official docs: neurondb.ai/docs

• NeuronDB/README.md
• NeuronAgent/README.md
• NeuronMCP/README.md
• NeuronDesktop/README.md

• Examples index
• Semantic search docs example
• RAG chatbot (PDFs) example
• Agent tools example
• MCP integration example

NeuronDB includes a benchmark suite to evaluate vector search, hybrid search, and RAG performance.

Run all benchmarks:

cd NeuronDB/benchmark
./run_bm.sh

This validates connectivity and runs the vector/hybrid/RAG benchmark groups.

To reproduce benchmark results:

# Use exact Docker image tags (see releases)
docker pull ghcr.io/neurondb/neurondb-postgres:v1.0.0-pg17-cpu

# Run with documented hardware profile
cd NeuronDB/benchmark
./run_bm.sh --hardware-profile "cpu-8core-16gb"

# Individual benchmark with exact parameters
cd NeuronDB/benchmark/vector
./run_bm.py --prepare --load --run \
  --datasets sift-128-euclidean \
  --max-queries 1000 \
  --index hnsw \
  --ef-search 40

# Vector benchmark
cd NeuronDB/benchmark/vector
./run_bm.py --prepare --load --run --datasets sift-128-euclidean --max-queries 100

# Hybrid benchmark
cd NeuronDB/benchmark/hybrid
./run_bm.py --prepare --load --run --datasets nfcorpus --model all-MiniLM-L6-v2

# RAG benchmark
cd NeuronDB/benchmark/rag
./run_bm.py --prepare --verify --run --benchmarks mteb

The root docker-compose.yml supports profiles:

• CPU (default): docker compose up -d
• CUDA: docker compose --profile cuda up -d
• ROCm: docker compose --profile rocm up -d

Ports differ per profile (see env.example):

• CPU: POSTGRES_PORT=5433
• CUDA: POSTGRES_CUDA_PORT=5434
• ROCm: POSTGRES_ROCM_PORT=5435

# Stop everything (keep data)
docker compose down

# Stop everything (delete data volumes)
docker compose down -v

# See status
docker compose ps

# Tail logs
docker compose logs -f neurondb neuronagent neuronmcp neurondesk-api neurondesk-frontend

Key operational considerations for production:

• Vacuum and bloat: Vector indexes require periodic maintenance. See NeuronDB/docs/operations/playbook.md
• Index rebuild guidance: When and how to rebuild HNSW/IVF indexes. See NeuronDB/docs/troubleshooting.md
• Memory configuration: Tune neurondb.maintenance_work_mem and index-specific parameters. See NeuronDB/docs/configuration.md

• Contributing: CONTRIBUTING.md
• Security: SECURITY.md - Report security issues to security@neurondb.ai
• License: LICENSE (proprietary)
• Changelog: CHANGELOG.md - See what's new
• Roadmap: ROADMAP.md - Planned features
• Releases: RELEASE.md - Release process