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, so a whole team can share one server, with roles and an audit log.

StrataKB finds the passages that answer a question and names the files they come from. Your MCP client writes the answer from them.

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 lists every file it skipped. 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, gets back the passages that match and the files they come from, and writes the answer.

No documents at hand? Try the Python PEPs example.

The guide

• Installation: the database, settings, and where your data goes
• Connecting a Client: add StrataKB to your MCP client and choose a role
• 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"]
    server <--> pg[("PostgreSQL + pgvector")]
    subgraph pg_schemas ["Schemas"]
        core["strata_core<br/>layers, files, users, audit log"]
        vec["strata_vectors<br/>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: answers you can prove, with every quote and fact checked against its source.