Home

StrataKB

StrataKB turns folders of your documents into a knowledge base that your AI tools can ask through the Model Context Protocol (MCP). Each folder becomes a layer: a searchable collection named after the folder. One PostgreSQL database holds every layer, with roles and an audit log.

Today it is for one developer or a small trusted group. The server runs on your machine over stdio, and each person says who they are in their own settings, so roles separate duties and are not a security boundary. A team server with real identities and per-layer access is planned (roadmap).

StrataKB finds the passages that answer a question and names the files they come from. Your MCP client writes the answer from them and checks it with strata_verify. When a passage comes from a layer in extractive mode, StrataKB answers itself, with the document's own sentences and a receipt.

Quick start

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

flowchart LR
    i["Install"] --> a["Add a folder"] --> c["Connect your client"] --> q["Ask"]

Loading

1. Install

git clone https://github.com/boudou/StrataKB.git
cd StrataKB
uv sync
uv run stratakb db up        # the database, in Docker on 127.0.0.1:5433

2. Add a folder

uv run stratakb add path/to/docs

It creates a layer named after the folder and reads the documents in it: PDF, Word, Markdown, HTML, plain text and more. It skips files that look like secrets, code or build output, and names the files it skipped (up to five per reason; --json lists them all). Run it again after you edit the documents: it reads only what changed.

The first run downloads a model of about 420 MB, and the first question downloads one of about 90 MB. To keep everything on this machine, see Where your data goes.

3. Connect your client

Add the server to your client's MCP configuration (for example a project .mcp.json):

{
  "mcpServers": {
    "stratakb": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/StrataKB", "python", "-m", "stratakb"],
      "env": {
        "DATABASE_URL": "postgresql://strata:strata_dev_password@127.0.0.1:5433/strata",
        "STRATA_USER": "developer",
        "STRATA_ROLE": "admin"
      }
    }
  }
}

Replace /path/to/StrataKB with the folder you cloned into, then restart the client. It starts StrataKB itself.

4. Ask

Ask your client a question about the documents, for example "How do we fail over the database?". The client calls StrataKB's strata_ask tool and gets back the passages that match and the files they come from. It writes the answer and checks it with strata_verify. On an extractive layer, strata_ask returns the answer itself: the document's own sentences and a receipt.

No documents at hand? Try the Python PEPs example.

Features

• Knowledge layers: a layer per folder or domain, each with its own chunking and routing rules; no code changes to add a new domain
• Layer presets: describe a layer and its source folders in one YAML file, then build or rebuild it in one call; see Presets
• Answers you can prove: cited passages with file, page, lines, headings and date, a check of the quotes and facts in a drafted answer (nothing_checked when there was nothing to check), the document's own sentences where paraphrase is not acceptable, and a receipt to open outside the chat; see Answers you can prove
• Dates and labels: citations say when a document was written, which document replaces it, and whether its file is archived; see Dates and labels
• Says what is missing: a note when a named clause is cut or left out, or when no passage holds a name the question asks about; see When part of the answer is missing
• Hybrid retrieval: pgvector HNSW similarity plus PostgreSQL full-text search, fused with Reciprocal Rank Fusion; strata_ask then reranks the results with a cross-encoder
• Query routing: when no layers are given, questions go to the right layers by each layer's patterns; a routed search that finds too little runs again across all layers, and the result says so. Layers you name yourself are never broadened
• Query rewriting (optional): with an Anthropic API key or any OpenAI-compatible endpoint (including a local Ollama), strata_ask expands a question into several searches in the knowledge base's own terminology
• Learns from use: records searches, rephrased questions and explicit feedback, and learns synonyms, query rewrites that worked and which layers a question belongs to
• Many formats: PDF, DOCX, Markdown, HTML, plain text, reStructuredText, AsciiDoc, CSV (up to 10,000 rows per file), JSON, XML/XSD and OpenAPI/AsyncAPI YAML, each split along its natural structure
• Local embeddings by default: all-mpnet-base-v2 runs on CPU with no API key; OpenAI or any OpenAI-compatible server (Ollama, LM Studio, vLLM) is optional
• Roles and audit: viewer, operator and admin roles on every tool, and an append-only audit log of searches and changes; see Tools and Roles and Audit
• Local-only switch: STRATA_LOCAL_ONLY=true refuses to start while any setting would send content off this machine, and keeps model downloads off; see Where your data goes
• Privacy guards: IBANs and card numbers are masked in logs, and IBANs, BICs and account numbers are scrubbed from stored queries and audited questions; secrets are redacted from audit entries; files whose names look like secrets are never read
• Read-only SQL: inspect the store with schema browsing, sample chunks, vector statistics and EXPLAIN

The guide

• Installation: the database, settings, and where your data goes
• Connecting a Client: add StrataKB to your MCP client and choose a role
• Configuration: every setting, where it comes from and when a change takes effect
• Tools: every tool, its role and what it does
• Layers and Presets: add a folder, what gets skipped, and build layers from a YAML file
• Asking and Searching: when to use strata_ask or strata_search, filters, confidence and feedback
• Roles and Audit: who can do what, what gets logged, and how personal data is handled
• Troubleshooting: common problems and how to fix them
• Glossary: the terms the other pages use

How it fits together

flowchart LR
    client["MCP client"] <-->|"stdio (JSON-RPC)"| server["StrataKB server"]
    cli["stratakb add"] --> pg
    server --> model["Local models<br/>embedding + reranker"]
    cli --> model
    server <--> pg[("PostgreSQL + pgvector")]
    subgraph pg_schemas ["Schemas"]
        core["strata_core<br/>layers, files, users, audit log, receipts"]
        vec["strata_vectors<br/>documents, sections, chunks"]
        learn["strata_learning<br/>interactions, rewrites, synonyms"]
    end
    pg --- pg_schemas

Loading

Source code and issues: https://github.com/boudou/StrataKB. Next up, in the roadmap: the rest of answers you can prove: an evaluation suite that measures the not-found thresholds, and structured tool output.