knowl

Knowl

Durable project knowledge for agents.

Knowl is a self-hosted knowledge sidecar for agentic applications. It turns durable sources into an inspectable Markdown knowledge base and returns bounded, provenance-backed evidence.

Quickstart · Connect an agent · Documentation · GitHub

What Users Get

Why Knowl

• Built for durable knowledge: keep accepted project knowledge beyond one chat or agent run.
• Human-inspectable: review the generated Markdown instead of hiding knowledge in an opaque memory store.
• Clear ownership: the host selects durable inputs and writes the final answer; Knowl maintains knowledge and retrieves evidence.
• Self-hosted: run it beside an agent with your own storage and maintainer provider.
• Recoverable: durable operations and local state resume safely after process restarts.

Knowl is not session memory, a workflow orchestrator, or the primary final-answer generator. Knowl does not answer the user itself.

Minimal Sidecar Quickstart

The quickstart runs the published v0.5.0 image with a checked-in example source. It requires Git, Docker Compose, curl, an OpenAI API key, and a model available to that key.

git clone https://github.com/baldaworks/knowl.git
cd knowl

export OPENAI_API_KEY='your-api-key'
export OPENAI_MODEL='a-model-available-to-your-account'
export KNOWL_OPERATOR_TOKEN='replace-with-a-local-secret'

docker compose -f deploy/sidecar/quickstart.compose.yaml up -d
curl -sS http://127.0.0.1:8080/readyz

The configured source synchronizes on startup. Check maintenance status:

docker compose -f deploy/sidecar/quickstart.compose.yaml \
  exec knowl knowl --config-dir /etc source status engineering

Then retrieve grounded evidence:

curl -sS --get \
  -H "Authorization: Bearer ${KNOWL_OPERATOR_TOKEN}" \
  --data-urlencode 'query=Engineering shared page' \
  http://127.0.0.1:8080/v1/retrieve

A successful response contains a non-empty evidence array with source provenance. /readyz confirms that the service and storage are ready; use source status to confirm that model-backed maintenance completed.

Stop the example without deleting its persistent volume:

docker compose -f deploy/sidecar/quickstart.compose.yaml down

The quickstart uses the hosted openai maintainer provider. Other configurations may use opencode_acp, which requires opencode acp on PATH and an authenticated OpenCode session. See configuration and operations for provider and source settings.

Connect an Agent

MCP Streamable HTTP is the primary agent-facing interface. Adapt these fields to your MCP client:

{
  "transport": "streamable_http",
  "url": "http://127.0.0.1:8080/mcp",
  "headers": {
    "Authorization": "Bearer <operator-token>"
  }
}

Knowl exposes three MCP tools:

• knowl_retrieve returns bounded evidence;
• knowl_ingest submits durable content or a source reference;
• knowl_operation reports durable operation status.

The equivalent HTTP endpoints are GET /v1/retrieve, POST /v1/ingest, and GET /v1/operations/{operation_id}. See the OpenAPI contract for request and response schemas.

How It Works

sources → Knowl → grounded evidence → host agent → final answer

Knowl stores immutable accepted source revisions under raw/ and semantic knowledge under wiki/. Source documents are never copied into wiki/. Initial bootstrap and automatic on_start synchronization are both optional. The workspace remains inspectable and portable, with SQLite at .knowl/knowl.sqlite providing the default local operational store:

workspace/
├── schema.md
├── raw/
├── wiki/
│   ├── index.md
│   └── ... semantic pages
└── .knowl/
    └── knowl.sqlite

See the source-to-wiki showcase for a complete checked-in example.

Run Knowl Your Way

Sidecar

Use the published container for a standalone MCP/HTTP service. Persist /var/lib/knowl, keep source mounts read-only, and pin an immutable image digest in production. The sidecar guide covers deployment, storage, authentication, and health checks.

Go library

• pkg/knowl provides plain-Go runtime composition;
• pkg/knowlfx adds Fx lifecycle integration;
• pkg/knowl/mcp provides the MCP adapter;
• pkg/knowl/types contains transport-neutral domain types.

Embedding changes composition, not the business contract. See the product design for architecture and ownership boundaries.

Documentation By Goal

Contributing

Contributions are welcome. Start with CONTRIBUTING.md for local setup, verification commands, and repository conventions.

License

Knowl is released under the MIT License.