Installation

Installation

You need Docker, uv and Git. If you don't have Python 3.12, uv installs it.

flowchart LR
    a["1. Clone"] --> c["2. uv sync"]
    c --> b["3. stratakb db up<br/>Postgres on 5433"]
    b --> d["4. stratakb add<br/>a folder"]
    d --> e["Connect a client"]

Loading

1. Get the code

git clone https://github.com/boudou/StrataKB.git
cd StrataKB

The defaults match the Docker database, so on your own machine you need no settings file. To change the passwords, see Passwords.

2. Install the server

uv sync

This also installs the stratakb command. uv run stratakb add <folder> adds a folder; uv run stratakb receipt <id> opens a receipt (--json for the tool's form); uv run stratakb (or stratakb serve, or python -m stratakb) starts the MCP server.

The server answers its client at once and, with the default local backend, loads the embedding model in the background; a search sent before the model is ready waits for it. The first start downloads the embedding model (about 420 MB) and the first strata_ask downloads the reranker (about 90 MB), both into your Hugging Face cache. After that, both load from the cache, and StrataKB works offline unless you turn on a provider listed in Where your data goes. A model setting that names a folder (EMBEDDING_MODEL=C:\models\mpnet, RERANKING_MODEL=/opt/models/reranker) loads from that folder only: a folder that is missing or holds no model fails with a message naming the setting and the folder, and nothing is downloaded. With HF_HUB_OFFLINE or TRANSFORMERS_OFFLINE set, a model missing from the Hugging Face cache fails with a message naming that variable.

3. Start the database

uv run stratakb db up

This starts PostgreSQL 16 with pgvector in the Docker container stratakb-db, on 127.0.0.1:5433, so it doesn't collide with a PostgreSQL already running on 5432. The data lives in the Docker volume stratakb-data. The command waits until the database accepts connections and builds the schema before it returns.

• Run it again any time: a running database keeps running and gets any missing schema updates, and a stopped one is started with its data.
• uv run stratakb db down stops the container and keeps the volume.
• --port picks another host port when the container is first created.
• If it prints a DATABASE_URL= line, your settings point at another database: put that line where it says.
• With no docker on PATH, or the Docker daemon not running, it exits with code 3 and says which.

It creates no strata_readonly role, so the SQL inspection tools stay off until you apply db/03_readonly_role.sql (see Roles and Audit).

Docker Compose, for development

A checkout also has a docker-compose.yml with the same database on port 5433 (container strata-postgres), which creates the read-only role too. Run docker compose up -d, or stratakb db up, not both on the same port. On the first start of an empty volume, Docker runs these files:

File	Creates
src/stratakb/core/sql/01_init.sql	Layers, ingestion runs, chunks with their vectors, users and the audit log
src/stratakb/core/sql/02_learning.sql	Interactions, feedback, and the synonyms and rewrites the server has learned
db/03_readonly_role.sql	The strata_readonly role used by the SQL inspection tools
src/stratakb/core/sql/04_ingested_files.sql	The table that tracks each ingested file

The server applies the remaining schema changes itself (see The schema). To start again from scratch, run docker compose down -v. This deletes all data.

Any other PostgreSQL

Any empty PostgreSQL 16 database with pgvector works as well. The server and stratakb add create the schema on first use, as long as the user in DATABASE_URL may create the vector and pg_trgm extensions. Before it creates anything, it names the database it sets up as host:port/database (never the user or password): in the server log (setting_up_database) and on stderr in stratakb add. It refuses to set up in postgres or in a database whose name starts with template, which usually means DATABASE_URL points at the wrong database: create one for StrataKB (CREATE DATABASE strata;) and point DATABASE_URL at it. A StrataKB schema already in such a database keeps working. Use pgvector 0.8 or later for complete results: older versions work, but a filtered search can return fewer results than it asks for, and the server logs hnsw_iterative_scan_unavailable. After upgrading an existing database's image, run ALTER EXTENSION vector UPDATE;. The strata_readonly role is not created for you: apply db/03_readonly_role.sql with psql as the owner of the schemas if you want the SQL tools (see Roles and Audit).

The schema

The schema files ship inside the package. At startup, and before stratakb add writes anything, StrataKB applies every numbered migration the database is missing, in order, and records it in strata_core.schema_migrations. An existing database is brought up to date the same way, so upgrading needs no manual SQL step. If the database user may not change the schema, the error names the SQL file to apply as the database owner; a user without USAGE on the StrataKB schemas is told which privilege is missing. A schema update waits at most 30 seconds for a lock another process holds, then stops and names the lock.

4. Check that it runs

uv run stratakb add path/to/docs

It creates a layer named after the folder and prints what it stored and skipped. See Layers and Presets. No documents at hand? The Python PEPs example fetches a few in seconds. Then connect a client.

Settings

Settings come from four sources, each overriding the one before:

flowchart LR
    d["Defaults"] --> u["User config.env"] --> c["File named by<br/>STRATAKB_CONFIG"] --> e["Environment<br/>variables"]

Loading

Source	Where
User config file	%APPDATA%\stratakb\config.env on Windows; $XDG_CONFIG_HOME/stratakb/config.env, else ~/.config/stratakb/config.env, elsewhere
STRATAKB_CONFIG	Any file you name; a missing file is logged and skipped by the server, and refused by stratakb add
Environment variables	Your shell, or the env block of your MCP client's configuration

Copy .env.example to the user config file to start. ./.env is not read unless you set STRATAKB_CONFIG=.env; when the server finds one it does not read, it logs a warning (dotenv_not_read). Keys the server does not know, such as DB_PASSWORD, are ignored, so one file can serve both the server and Docker (see Passwords). Configuration has the full table of settings.

The server keeps the settings it started with for strata_admin_health, strata_search, strata_ask, strata_verify, query rewriting, the query embedding and the raw-query audit setting: a config file edited while the server runs changes nothing for them until you restart it. strata_ingest_documents and strata_apply_preset read the config files on each call. The server reads STRATA_USER and STRATA_ROLE once, when it starts; changing either takes a restart.

Passwords

docker compose still reads ./.env itself, for its own variables: DB_PASSWORD, READONLY_DB_PASSWORD and DB_PORT. Unless the server only runs on your own machine, change the passwords before the first docker compose up -d:

cp .env.example .env          # for docker compose

Change DB_PASSWORD and READONLY_DB_PASSWORD in .env, and the matching DATABASE_URL and READONLY_DATABASE_URL in your user config.env (or set STRATAKB_CONFIG=.env so the server reads the same file). The passwords apply when the data volume is created.

Where your data goes

By default nothing leaves this machine except what you choose to send: your documents stay in PostgreSQL, and the embedding and reranking models run in-process. Each other path is off until a setting turns it on.

Path	What leaves	Turned on by	Blocked by STRATA_LOCAL_ONLY
PostgreSQL	Documents, chunks, stored queries, audit entries	DATABASE_URL (always)	No
Your MCP client and its language model	Retrieved text, sources	Every search and ask	No
Anthropic query rewriting	Questions and layer descriptions	ANTHROPIC_API_KEY	Yes
Rewrite endpoint on another host	Questions and layer descriptions	QUERY_REWRITE_PROVIDER=openai_compatible with QUERY_REWRITE_BASE_URL and QUERY_REWRITE_MODEL set	Yes
OpenAI embeddings	Documents and questions	EMBEDDING_BACKEND=openai without EMBEDDING_BASE_URL	Yes
Embedding server on another host	Documents and questions	EMBEDDING_BACKEND=openai with EMBEDDING_BASE_URL	Yes
Hugging Face downloads	Nothing about your documents; model files come in	The first start, the first stratakb add and the first strata_ask	Yes

A rewrite endpoint or embedding server on this machine (127.0.0.1, ::1 or localhost) is allowed with the switch on.

With STRATA_LOCAL_ONLY=true the server refuses to start while any blocked path is configured, and the error names each setting that caused it. strata_search, strata_ask and query rewriting use the settings the server started with. strata_ingest_documents and strata_apply_preset read the config files on each call and check the switch there, so a key added later is refused. Models load from local files only; a model that is not installed fails with a message that says how to install it. The switch does not cover the database: DATABASE_URL may point at a shared database on purpose. stratakb add checks the embedding path before it starts: with a blocked one configured it refuses with exit 2 (reason local_only in --json), names the setting and writes nothing. The OpenAI and Anthropic SDKs also read OPENAI_BASE_URL and ANTHROPIC_BASE_URL; StrataKB treats them as the destination of those paths, and STRATA_LOCAL_ONLY checks them too. Requests to EMBEDDING_BASE_URL and QUERY_REWRITE_BASE_URL never carry OPENAI_API_KEY, OPENAI_ADMIN_KEY, OPENAI_ORG_ID or OPENAI_PROJECT_ID.

strata_admin_health always lists the switch (local_only) and the active outbound providers (outbound: provider, purpose, what it sends, destination host and the setting that turns it on). The outbound list never shows keys, credentials, paths or ports.

StrataKB cannot control what your MCP client's language model does with the retrieved text. If the client uses a cloud model, the retrieved text goes to that provider.

Development install

uv sync --extra dev
uv run pytest                  # the integration tests need the database running
uv run ruff check src tests

See CONTRIBUTING.md before opening a pull request.