wexaai/cognodb: stdio transport — for Claude Desktop and local AI tools.

CognoDB
A cypher-compatible context graph database for AI Agents written in Go

cognodb.com · GitHub · Deploy · Docs

CognoDB is an open-source graph database that speaks the Bolt protocol (v5.0–5.4) and understands Cypher. Connect with any official Neo4j driver — Python, Go, JavaScript, Java, .NET — no code changes required.

Quick Start

The fastest way to get running:

docker run -p 7687:7687 ghcr.io/wexaai/cognodb:latest

Connect at bolt://localhost:7687 with username cognodb, password password.

Other install options

curl -fsSL https://raw.githubusercontent.com/wexaai/cognodb/main/install.sh | bash

cognodb                   # in-memory (data lost on exit)
cognodb --storage local   # persistent on-disk storage

git clone https://github.com/wexaai/cognodb.git && cd cognodb
docker compose up -d

git clone https://github.com/wexaai/cognodb.git && cd cognodb
docker compose -f deployments/docker/docker-compose.yml up -d

go install github.com/wexaai/cognodb/cmd/cognodb@latest
cognodb

git clone https://github.com/wexaai/cognodb.git
cd cognodb && make build
./bin/cognodb

See Deployment Guide for systemd, Kubernetes/Helm, and all configuration options.

MCP Server (optional)

CognoDB has a built-in Model Context Protocol server. It is completely optional — the database runs normally without it. When enabled, any MCP-compatible AI assistant (Claude, ChatGPT, Cursor, …) can query and write to your graph in natural language.

The MCP server exposes two tools:

Start the MCP server

# The Bolt server is NOT started in this mode; the process is a pure MCP server.
cognodb --mcp

# With persistent storage (graph survives restarts):
cognodb --mcp --storage local --data-dir ~/.cognodb

# HTTP/SSE transport — for web clients and ChatGPT.
# Bolt runs on :7687 as normal; MCP HTTP runs alongside on the chosen port.
cognodb --mcp-port 8811

# Both Bolt AND MCP HTTP at the same time:
cognodb --storage local --data-dir ~/.cognodb --mcp-port 8811

Connect Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows) and restart Claude:

{
  "mcpServers": {
    "cognodb": {
      "command": "cognodb",
      "args": ["--mcp", "--storage", "local", "--data-dir", "/Users/you/.cognodb"]
    }
  }
}

No local install? Use Docker instead:

{
  "mcpServers": {
    "cognodb": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/Users/you/.cognodb:/data",
        "ghcr.io/wexaai/cognodb:latest",
        "--mcp", "--storage", "local", "--data-dir", "/data"
      ]
    }
  }
}

Once connected, Claude can store and retrieve structured knowledge, build knowledge graphs from your conversations, and answer questions by running Cypher against the graph.

Verify it works

# Start the MCP HTTP server
cognodb --mcp-port 8811 &

# Health check
curl http://localhost:8811/health

# List available tools
curl -s -X POST http://localhost:8811/messages \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# Run a Cypher query through MCP
curl -s -X POST http://localhost:8811/messages \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"query","arguments":{"cypher":"CREATE (n:Person {name:\"Alice\"}) RETURN n.name"}}}'

See doc/mcp.md for the full HTTP/SSE protocol, ChatGPT plugin setup, and LLM integration test.

Benchmarks

All numbers are from bench/results.json and bench/token_results.json, run on a single 8-core Linux host. Databases are co-located (no network hop). Full methodology and raw data are in bench/.

Startup & footprint

CognoDB starts cold in 7 ms and idles at 15 MB — critical for agent workloads that spin up per-request or per-session.

Throughput & latency (10k nodes, 50k edges, degree-5 graph)

Neo4j and MongoDB are mature engines with years of query optimisation — CognoDB's in-memory mode is competitive on load and write throughput. Traversal latency headroom exists and is the active development focus.

Token cost for AI agents (graph-retrieval vs. full-context dump)

Agents that query CognoDB for relevant context instead of dumping the whole corpus into the prompt use dramatically fewer tokens — and the cost stays flat as the graph grows.

Tokens are counted with the GPT-4 BPE tokenizer (tiktoken cl100k_base) over identical rendered text — no numbers invented. The graph-retrieval path fetches the 2-hop neighborhood around the query entities; the baseline dumps every node and edge.

Real LLM agent benchmark (tool-use loop)

Measured with actual LLM calls via AWS Bedrock. The agent uses CognoDB as a run_cypher tool and issues real Cypher queries per question; the baseline dumps the full corpus into the prompt.

Run the benchmarks yourself:

# Token benchmark (no LLM calls, uses tiktoken)
pip install tiktoken neo4j
bin/cognodb &
python bench/token_benchmark.py

# Performance benchmark (requires running Neo4j and MongoDB for comparison)
go run ./bench --help

Features

• Full Bolt protocol — works with all official Neo4j drivers out of the box
• Cypher query language — CREATE, MATCH, MERGE, DELETE, SET, REMOVE, WITH, UNWIND, ORDER BY, SKIP, LIMIT, DISTINCT, and more
• Variable-length path traversal — [*1..5], shortestPath, allShortestPaths
• Schema operations — indexes (property, composite), constraints (UNIQUE, EXISTS, NODE KEY)
• ACID transactions — BEGIN, COMMIT, ROLLBACK with full isolation
• EXPLAIN / PROFILE — query plan introspection
• 40+ built-in functions — scalar, string, math, list, temporal, type coercion
• RBAC authentication — admin, architect, editor, reader, publisher roles
• Pluggable storage — in-memory (default), local on-disk, MongoDB
• Backup & restore — cognodb-dump / cognodb-restore CLI tools
• Neo4j migration — import from Neo4j CSV exports with neo2cognodb

Connect with Any Neo4j Driver

Python

from neo4j import GraphDatabase

driver = GraphDatabase.driver("bolt://localhost:7687", auth=("cognodb", "password"))

with driver.session() as session:
    session.run("""
        CREATE (a:Person {name: 'Alice', age: 30})
        CREATE (b:Person {name: 'Bob',   age: 25})
        CREATE (a)-[:KNOWS {since: 2020}]->(b)
    """)

    result = session.run("""
        MATCH (a:Person)-[:KNOWS]->(b:Person)
        RETURN a.name AS from, b.name AS to
    """)
    for record in result:
        print(f"{record['from']} knows {record['to']}")

driver.close()

Go

package main

import (
    "context"
    "fmt"
    "github.com/neo4j/neo4j-go-driver/v5/neo4j"
)

func main() {
    ctx := context.Background()
    driver, _ := neo4j.NewDriverWithContext("bolt://localhost:7687",
        neo4j.BasicAuth("cognodb", "password", ""))
    defer driver.Close(ctx)

    session := driver.NewSession(ctx, neo4j.SessionConfig{})
    defer session.Close(ctx)

    session.Run(ctx, `CREATE (a:Person {name: 'Alice'})-[:KNOWS]->(b:Person {name: 'Bob'})`, nil)

    result, _ := session.Run(ctx, `MATCH (n:Person) RETURN n.name AS name`, nil)
    for result.Next(ctx) {
        fmt.Println(result.Record().Values[0])
    }
}

JavaScript

const neo4j = require("neo4j-driver");

const driver = neo4j.driver(
  "bolt://localhost:7687",
  neo4j.auth.basic("cognodb", "password")
);
const session = driver.session();

await session.run(
  "CREATE (a:Person {name: $name})-[:KNOWS]->(b:Person {name: $friend})",
  { name: "Alice", friend: "Bob" }
);

const result = await session.run("MATCH (n:Person) RETURN n.name AS name");
result.records.forEach((r) => console.log(r.get("name")));

await session.close();
await driver.close();

Java

import org.neo4j.driver.*;

try (Driver driver = GraphDatabase.driver("bolt://localhost:7687",
        AuthTokens.basic("cognodb", "password"));
     Session session = driver.session()) {

    session.run("CREATE (a:Person {name: 'Alice'})-[:KNOWS]->(b:Person {name: 'Bob'})");

    Result result = session.run("MATCH (n:Person) RETURN n.name AS name");
    while (result.hasNext()) {
        System.out.println(result.next().get("name").asString());
    }
}

Tip: CognoDB also accepts neo4j as the username for drop-in compatibility with existing tooling and connection strings.

Cypher Support

CognoDB supports a broad subset of the Cypher query language. See Cypher Compatibility for the full matrix.

Architecture

Neo4j Driver ──► Bolt Server (PackStream codec, auth, Bolt 5.0–5.4)
                      │
                      ▼
                Cypher Parser (hand-written recursive descent, ~14.5 µs/op)
                      │
                      ▼
                AST + Semantic Analysis
                      │
                      ▼
                Optimizer (rule-based + cost-based)
                      │
                      ▼
                Execution Engine (Volcano pull-based iterators)
                      │
                      ▼
                Storage (in-memory │ local on-disk │ MongoDB │ sharded)

See Architecture for design decisions and storage schema details.

Docker Image

The official image is published to GitHub Container Registry and updated automatically on every release:

# Latest release
docker run -p 7687:7687 ghcr.io/wexaai/cognodb:latest

# Specific version
docker run -p 7687:7687 ghcr.io/wexaai/cognodb:0.1.0

# With persistent local storage
docker run -p 7687:7687 -v cognodb_data:/data \
  ghcr.io/wexaai/cognodb:latest --storage local --data-dir /data

Available tags: latest, main, and semver tags (0.1.0, 0.1, 0). Platforms: linux/amd64, linux/arm64.

CLI Tools

# Export
cognodb-dump --out ./backup/

# Import
cognodb-restore --in ./backup/

# Migrate from Neo4j
neo2cognodb --nodes nodes.csv --rels rels.csv --out ./backup/

Configuration

See Configuration Reference for query limits, cache tuning, and security settings.

Documentation

• Getting Started — installation, first queries, driver examples
• Deployment Guide — installer, Docker, Docker Compose, systemd, Kubernetes/Helm
• MCP Server — connect Claude Desktop, ChatGPT, and any MCP-compatible AI tool
• Developer Guide — complete Cypher tutorial, agent integration, operations
• Architecture — pipeline, design decisions, storage schema
• Configuration — server, storage, query limits, cache, security
• MongoDB Backend — production persistence backend, config, local replica set, operations
• Cypher Compatibility — supported features matrix
• Architecture Decision Records — rationale behind key design choices

Used in Production

CognoDB powers the personal and enterprise knowledge graphs at Wexa.ai — an AI workspace that builds a persistent, queryable graph of your work across tools, people, and projects. Every relationship, document reference, and workflow dependency is stored as a graph node and traversed in real time as agents answer questions and take actions.

If you're using CognoDB in production, feel free to open a PR to add yourself here.

Security

To report a security vulnerability, please see SECURITY.md.