NovaCortex

Self-hosted, graph-native memory for AI agents. Typed memories, semantic vector search, a relation graph, a knowledge base, and native MCP — all running on your own infrastructure. Use it from Claude/Cursor (MCP), the REST API, the CLI, or the TypeScript / Python SDKs.

What it is

NovaCortex gives your agents a persistent, queryable memory:

• Memory types — episodic, semantic, procedural, working — with salience & decay.

• Semantic search — natural-language queries are embedded server-side and matched via a Qdrant vector index (with transparent substring fallback when embeddings are off).

• Relation graph — typed edges (causes, supports, contradicts, supersedes, …); your agent asserts causal/typed links, NovaCortex stores and serves the graph.

• Memory intelligence (opt-in) — with any OpenAI-compatible LLM configured (LLM_MODEL, incl. fully-local Ollama), NovaCortex distills conversations into discrete memories (/memories/ingest, MCP memory_ingest) and resolves conflicts append-only: superseded facts get typed supersedes edges + an invalidatedAt stamp instead of being deleted — history stays queryable and auditable.

• Knowledge base — drop in documents, get auto-generated semantic memories.

• Namespaces — isolate memory per agent/project.

• Portable (PMF) — export/import the whole graph as JSON, binary MessagePack (~60% smaller), or AES-256-GCM-encrypted, with Merkle + content-hash integrity and differential/streaming variants. No lock-in.

• Ops-ready — opt-in OpenTelemetry traces (OTEL_EXPORTER_OTLP_ENDPOINT), scope-gated tokens, audit log, webhooks.

• Interfaces — MCP server, REST API (+ Swagger), CLI, @novacortex/sdk (TS) and novacortex (Python).

Open-core. The self-hostable core in this repo is Apache-2.0 (see LICENSE). The free tier runs fully self-hosted with no key. Pro/Enterprise unlock more namespaces + federation via an ed25519-signed license key — the build embeds only the public key, so keys are verified offline and cannot be forged. See pricing.

Related MCP server: grafeo-mcp

Quick start (self-host, ~5 min)

Requirements: Docker + Docker Compose. Works on Unraid and any Docker host.

git clone https://github.com/Nova-Cognitive-Systems/novacortex.git
cd novacortex

# 1. Generate strong secrets into .env
./scripts/gen-env.sh
#    For fully-local semantic search (no cloud, bundled Ollama sidecar):
#    ./scripts/gen-env.sh --local-embeddings

# 2. (generic Docker host) keep data next to the repo; (Unraid) use appdata:
#    edit .env -> APPDATA=./data            (generic)
#    edit .env -> APPDATA=/mnt/user/appdata/novacortex   (Unraid)
#    Optional: set OPENAI_API_KEY for hosted (OpenAI) embeddings instead.

# 3. Start the stack (pulls pinned multi-arch images from GHCR)
docker compose up -d
#    with local embeddings: docker compose --profile local-ai up -d

# 4. Grab the one-time bootstrap code from the logs
docker logs novacortex-api 2>&1 | grep -A1 "Bootstrap code"

Then open the Web UI at http://localhost:3000 (or http://<host-ip>:${WEB_PORT}), paste the nc_boot_… bootstrap code on the login page to mint your admin token, and you're in. The REST API is at http://localhost:3001 (Swagger at /docs).

Data lives under ${APPDATA} (bind-mounted), so it survives container/image rebuilds.

Privacy & embeddings

NovaCortex stores and serves all memory data on your own infrastructure. Semantic search activates in one of two ways:

• Fully local (recommended for the privacy-first path): start the stack with the local-ai compose profile (./scripts/gen-env.sh --local-embeddings, then docker compose --profile local-ai up -d). An Ollama sidecar computes embeddings on your host — no memory text ever leaves your infrastructure.

• Hosted: set OPENAI_API_KEY, at which point memory text is sent to OpenAI (or any OpenAI-compatible server you point OPENAI_BASE_URL at) to compute embeddings.

Without either, search falls back to local substring matching — the API logs this at startup and /health (plus the Settings page) shows the active search mode, so a silent degrade is visible. A mismatch between the embedding model's dimension and QDRANT_VECTOR_SIZE fails startup loudly instead of silently storing nothing.

Use it from an agent (MCP)

.mcp.json in this repo registers the MCP server for Claude Code / Cursor. Point its SURREALDB_* / QDRANT_* env at the same store your deployment uses so memory is shared across MCP, the REST API, and the Web UI.

// Claude Desktop / Cursor / Claude Code (.mcp.json)
{
  "mcpServers": {
    "novacortex": {
      "command": "node",
      "args": ["<repo>/packages/mcp-server/dist/index.js"], // npx @novacortex/mcp once published
      "env": {
        "SURREALDB_URL": "http://localhost:8000/rpc",
        "SURREALDB_NAMESPACE": "novacortex", "SURREALDB_DATABASE": "production",
        "SURREALDB_USER": "root", "SURREALDB_PASS": "<your pass>",
        "QDRANT_URL": "http://localhost:6333",
        "OPENAI_API_KEY": "…", "LLM_MODEL": "…" // optional: semantic search + intelligence
      }
    }
  }
}

Tools: memory_store, memory_search (hybrid + explain traces), memory_recall, memory_relate, memory_update, memory_ingest (LLM fact extraction), memory_current (supersedes-chain resolution), memory_status, memory_wakeup (progressive disclosure: depth: "index" = ~150-token index, drill down on demand), session_*.

SDKs

import { NovaCortexClient } from '@novacortex/sdk';
const nc = new NovaCortexClient({ baseUrl: 'http://localhost:3001', token });
await nc.memories.create({ content: 'The user prefers dark mode', memoryType: 'semantic', namespace: 'agent' });
const { data, mode } = await nc.search({ query: 'what does the user like?', namespace: 'agent' });

from novacortex import NovaCortexClient
nc = NovaCortexClient("http://localhost:3001", token)
nc.memories.create("The user prefers dark mode", namespace="agent")
res = nc.search("what does the user like?", namespace="agent")

Development

npm ci
npm run build --workspace=packages/core
npm run dev:db          # SurrealDB + Qdrant + Redis in Docker
npm run dev             # API on :3001 (from source)
npm run dev:web         # Web UI on :3000
npm test                # full suite (needs the dev stack up)

Full developer/deploy docs live in docs/novacortex-docs.

Deployment variants

• docker-compose.yml — supported self-host path for any Docker host. Pulls pinned GHCR images, secure-by-default, optional local-ai profile (Ollama sidecar for embeddings + intelligence).

• docker-compose.unraid.yml — the same stack with Unraid appdata defaults. Install it with the Docker Compose Manager plugin; templates/unraid/ has the step-by-step guide plus Community Apps templates for the Web UI and API containers on their own.

• docker-compose.gpu.yml — NVIDIA GPU override for the Ollama local-AI sidecar (docker compose --profile local-ai -f docker-compose.yml -f docker-compose.gpu.yml up -d).

• docker-compose.dev.yml — local development (builds from source, hot-reload).

• docker-compose.traefik.yml — ⚠️ experimental Traefik/Let's-Encrypt variant, not part of v1 (needs a traefik/ config tree that isn't shipped yet).

Licensing & tiers

The free tier needs no key. Pro/Enterprise keys are ed25519-signed and validated offline against an embedded public key — set one via LICENSE_KEY or POST /license/activate.

Issuing keys (for the provider). The build only verifies keys; minting requires the private signing key, which never ships in the OSS image:

node scripts/gen-license-keypair.mjs            # writes config/.license-signing-key.pem (gitignored), prints the public key
# embed the printed public key via NOVACORTEX_LICENSE_PUBKEY (or DEFAULT_LICENSE_PUBKEY)
node scripts/issue-license.mjs --email you@example.com --tier pro   # prints a signed nclic.… key

(Stripe checkout is rolling out as a separate billing service; for now request Pro access via GitHub Discussions.)

Security

See SECURITY.md. Secrets are generated by scripts/gen-env.sh and the self-host compose fails fast if they're missing. To expose the API cross-origin, set CORS_ORIGINS.

License

Apache-2.0 for the open-source core. © 2026 Nova Cognitive Systems.