Komplyt Zero

Komplyt Zero

An open-core memory graph for your AI tools. Run it yourself, or use ours in the EU.

Agents lose the reasoning behind a decision when the session ends, and each client keeps separate notes. Zero is an MCP server that gives Claude, ChatGPT, Cursor and any other MCP client one shared memory. Agents record decisions, problems and approaches together with the reason, as typed nodes in a graph. A later session, in any client, finds them by meaning instead of keyword, so the reasoning behind last month's choice is there when someone is about to undo it. It is for developers who use several AI clients on the same product, and for teams that keep re-deciding things because nobody remembers why.

A notes file grows until nobody reads it, and a plain vector store returns the closest text with nothing around it. Zero keeps the reason with each decision, links related nodes so a hit brings its context along, and lets knowledge nobody uses drop down the ranking. Nothing is deleted. It stores what the agent was asked to keep, not your chats.

The core is Apache-2.0. The team features in src/ee/ are source-available: free for noncommercial use under PolyForm Noncommercial, with a commercial licence for everything else. Zero also runs on SurrealDB (Business Source License), so the repository as a whole is not OSI open source. Details are in Licence.

To try the hosted service (free for one person, data stored in Frankfurt), add it to Claude Code and run /mcp to sign in. To run it on your own machine, see Getting started.

claude mcp add --transport http komplyt-zero https://kg.kompl.yt/mcp

What it looks like

An agent working on a webhook service starts a session, creating the project the first time:

{ "tool": "kg_session_start", "arguments": { "project": "acme-api", "create_project": true } }

It then records a decision:

{
  "tool": "kg_node_create",
  "arguments": {
    "type": "decision",
    "project": "acme-api",
    "tags": ["architecture", "webhooks"],
    "content": "Webhook delivery uses a Postgres job table (SKIP LOCKED) instead of Redis or SQS. Why: under 1k jobs/min, Postgres already runs, and enqueueing in the same transaction as the business write means no lost events. Revisit above 10k jobs/min."
  }
}

Three weeks later, in a different client, someone asks a question that shares no keywords with it:

{
  "tool": "kg_query",
  "arguments": { "text": "why don't we use Redis for background jobs?", "project": "acme-api" }
}

The decision comes back first. Spreading activation also returns the nodes linked to it, such as the open problem about retry storms that someone related to it last week.

How it ranks what comes back

Every node carries an embedding and a decay score. A query ranks candidates by 0.7 × cosine similarity + 0.3 × decay score, then follows the graph's edges for up to three hops (two by default) to pull in related nodes, each hop weakening the signal by half.

The decay score is how the graph forgets. Each time a session starts in a project, every node in that project keeps 85 % of its score, so scores fall off exponentially. Nodes that agents update climb back toward a ceiling of 0.85, by more when they sit in a dense neighbourhood, and a query gives a smaller lift. Knowledge that keeps being used stays near the top, and knowledge nobody touches fades without anyone having to curate it. Decay never deletes anything; a faded node still turns up when a query matches it closely enough.

The graph, the decay and the spreading activation are all in this repository under Apache-2.0. The hosted service runs the same ranking code.

Getting started

Use the hosted service. This is the fastest route and needs no infrastructure. Add https://kg.kompl.yt/mcp as a custom connector in Claude or ChatGPT, or in Claude Code (the command is at the top of this page).

In Claude Code, run /mcp afterwards to sign in. Data is stored in Frankfurt. Step-by-step instructions for each client are in docs/connectors.md.

Run it yourself, with Docker (quickstart). The compose file starts SurrealDB, Ollama embeddings and the server with one command. It is a quickstart for one person on one machine, not production grade: no authentication (local mode), a single unreplicated database, no backups, no TLS, and secrets passed as plain environment variables. For anything shared or long-lived, follow docs/self-hosting.md. It needs Docker with the Compose plugin: docker compose version should print a version. Debian's docker.io package lacks it, so install docker-compose (Ubuntu: docker-compose-v2) or Docker's own packages.

git clone https://github.com/Komplyzen/komplyt-zero.git
cd komplyt-zero
[ -f .env ] || { umask 077; printf 'KG_JWT_SECRET=%s\nDB_ROOT_PASS=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env; }
docker compose up --build
claude mcp add --transport http zero http://localhost:3000/mcp

The first start downloads the embedding model (bge-m3, about 1.2 GB). The server runs in local auth mode (KG_AUTH_MODE=local): no tokens, one fixed user in one fixed tenant, and a default container called "Company Knowledge" created on first use. That suits one person on one machine, so compose publishes the port on 127.0.0.1 only. Don't publish the port beyond localhost, or put a proxy in front of it, unless the proxy authenticates callers. Once it is up, http://localhost:3000/docs shows the server's documentation page and http://localhost:3000/health answers when it is ready.

Port 3000 already in use? Then the kg container won't start ("address already in use"). Add KG_PORT=3100 (any free port) to .env, run docker compose up -d again, and use http://localhost:3100/mcp and http://localhost:3100/docs instead.

KG_JWT_SECRET and DB_ROOT_PASS are plain environment variables of the containers, so anyone with access to the Docker daemon can read them with docker inspect. SurrealDB reads its root password only from an argument or environment variable (no password file), so compose can't hide it. The command above writes both secrets to .env once (mode 600, git-ignored; the [ -f .env ] guard never overwrites it). Keep that file: the database keeps the first DB_ROOT_PASS and the first KG_JWT_SECRET hash, so a lost or regenerated value makes the next start fail (kg crash-loops, migrate gets a 401). Existing installs from before the hardening (root/root): put DB_ROOT_PASS=root and your original KG_JWT_SECRET in .env; tested, data and migrations carry over.

Run it yourself, without Docker for the server. Zero needs Bun, a SurrealDB instance and an embedding provider:

git clone https://github.com/Komplyzen/komplyt-zero.git
cd komplyt-zero/src
bun install
../scripts/local-db.sh up        # SurrealDB v3.2.4 in Docker, prints the KG_DB_* values
SURREAL_HTTP=http://127.0.0.1:8000 SURREAL_USER=root SURREAL_PASS=root KG_DB_NAME=local ../scripts/migrate.sh
cp .env.example .env             # fill in the values. For single-user use: set KG_AUTH_MODE=local and
                                 # comment out KOMPLYT_JWKS_URL and KOMPLYT_ISSUER (local mode refuses to start with them)
bun index.ts

In local mode (KG_AUTH_MODE=local) you need no identity provider: the server listens on 127.0.0.1:3000 unless you set LISTEN_ADDR, and rejects browser requests from other origins, other Host values (KG_LOCAL_ALLOWED_HOSTS adds some) and non-JSON bodies.

For a team or a public deployment, keep the default mode: the server accepts bearer JWTs from an OIDC issuer you point it at (Keycloak, Zitadel, Authentik, or anything that publishes a JWKS and can add a custom claim), and every token needs a tenantId claim, which scopes each query to one tenant. The modes can't be combined: local mode refuses to start when KOMPLYT_JWKS_URL or KOMPLYT_ISSUER is set. docs/self-hosting.md covers the full setup and the claims the server expects.

Use it from npm, as a stdio server. With your own SurrealDB and embedding provider, npx @komplyzen/komplyt-zero mcp starts Zero as a stdio MCP server for your client. It reads the same KG_DB_* and EMBEDDING_* settings, and KG_AUTH_MODE=local skips the login. On Linux it needs libsecret (Debian and Ubuntu: sudo apt install libsecret-1-0), because its credential store is a native module; without it the command fails at start with ERR_DLOPEN_FAILED. For a first try, Docker is simpler, since it brings SurrealDB and Ollama along.

Using it well

The server tells every client how to use it, but a few habits separate a graph that answers questions from a pile of notes. Query before you record, because the server doesn't deduplicate. Put the reason in the content, since only the content is embedded. Start each session with the right project, because decay and filtering key on it. At the end, re-activate the nodes you relied on so they stay findable.

docs/using-zero.md collects what we learned running Zero on our own work since early 2026: what to record and what to leave out, how to replace a decision without losing its history, which queries retrieve badly, and the end-of-session routine we use. Ready-to-copy agent instructions and a session-close skill are in examples/.

Tools

Only kg_node_update changes what a node says. Querying, relating and starting sessions change usage scores, which shape future rankings. Pass read_only: true to kg_query when you are only looking, for example from a dashboard. The same operations are available over REST under /api/v1, described by /api/v1/openapi.json. Full parameter schemas are in src/contracts.ts. If you used the tools under their earlier names, see docs/migration-tool-split.md.

Embeddings

Zero uses Cohere's embed-multilingual-v3.0 by default. Ollama works for fully local embeddings, with one constraint: the vector index has 1024 dimensions, so the model must produce 1024-dimension vectors (bge-m3 and mxbai-embed-large do; Ollama's default nomic-embed-text does not). The server checks the dimension at boot and refuses to start on a mismatch.

EMBEDDING_PROVIDER=ollama
EMBEDDING_BASE_URL=http://localhost:11434   # OLLAMA_URL is accepted as an alias
EMBEDDING_MODEL=bge-m3                      # optional; OLLAMA_MODEL is accepted as an alias

Run one provider per install: every stored vector must come from the same model. Switching provider or model on an existing database needs bun run bin/reembed.ts (use --dry-run first); until it finishes, queries compare against vectors from both models and results from nodes not yet re-embedded are unreliable. Cohere takes EMBEDDING_API_KEY (COHERE_API_KEY is still accepted). EMBEDDING_PROVIDER=fixture gives deterministic vectors without network calls, which is what the tests use. To add a provider, write an EmbeddingAdapter in src/embed.ts, list it in ADAPTER_FACTORIES and add its metadata to src/embed-registry.ts; env validation then accepts the new name with no other change.

Configuration

The variables you need for a first run are below; src/.env.example lists the rest.

Open core and the hosted product

This repository is the engine. In local auth mode, or once it has an OIDC issuer to trust, it is a complete memory for one person, which you run yourself, record into and query from any MCP client.

Working as a team is the paid part. The engine enforces who may read which container of nodes, but the code that sets up team work lives in src/ee/ and belongs to Komplyt Teams: the API that creates shared containers and grants colleagues access to them, the OAuth integration for the Claude and ChatGPT connector directories, and the admin surface. Komplyzen also runs the engine as a hosted service: Komplyt Zero is free for one person, Personal raises the limits for heavier individual use, and Teams is priced per seat. Above that sits the Komplyt Platform, a separate, closed product that runs expert-authored workflows against the graph. Current tiers and prices are on kompl.yt/zero, and questions about Teams or the Platform go to [email protected].

Licence

The engine is licensed under Apache-2.0 (see LICENSING.md for the split). The code in src/ee/ (OAuth discovery metadata for connector directories, the REST API for managing shared containers, and the admin and purge routes) is not part of the Apache-2.0 engine and is not covered by that licence. It is source-available under the PolyForm Noncommercial License 1.0.0, which allows noncommercial use only, and Komplyzen offers it under a commercial licence as well ([email protected]). Only those terms apply to it, although the Docker image contains it. The server runs without src/ee/; it then logs that it is the open-source edition and leaves those routes out.

Zero stores its data in SurrealDB, which is licensed under the Business Source License 1.1. Self-hosting SurrealDB for your own use is permitted under that licence, but that licence, like the one on src/ee/, is not OSI open source, so we call Zero open core and don't describe the repository as open source.

Contributing and security

Contributions are welcome; CONTRIBUTING.md covers the setup, the test database and what a pull request needs. Report vulnerabilities privately to [email protected], as described in SECURITY.md. For questions and a chat with the people building it, join us on Discord.

Zero is built by Komplyzen GmbH in Berlin.