README
¶
Ken
An AI-first knowledge base: a place for an AI coding agent to store and retrieve curated knowledge — solutions, caveats, pitfalls, design decisions — gathered while it works, so hard-won answers are neither reinvented nor missed.
- Primary user: the AI, over the Model Context Protocol (
/mcp). - Secondary user: the human curator, over a web UI (browse / search / promote).
Project site: https://ken.quest.mx
The load-bearing idea: the AI authors, the human promotes. Everything an agent writes lands as a proposed revision it can use immediately — but the curated head moves only when a human promotes it. An agent can never curate; that exclusion is the whole point. Nothing is ever overwritten: enhancements append, and superseded versions stay searchable, so the answer that was right on the old dependency version is still there when you go back to it.
Try it in 60 seconds
go run ./cmd/ken --demo-seed # add KEN_DEV_TOKEN=dev-secret for MCP access
Open http://localhost:8080 — the first visit runs a one-time setup wizard that creates your curator account. A demo entry is already seeded, so search and the entry view have something to show.
To let an agent use it, start with a dev token and register the endpoint:
KEN_DEV_TOKEN=dev-secret go run ./cmd/ken --demo-seed
claude mcp add --transport http ken http://localhost:8080/mcp --header "Authorization: Bearer dev-secret"
Ken sends the agent its own operating instructions on connect, so there is no prompt to
paste. Ask it to search for something and it will use kb_search unprompted.
(KEN_DEV_TOKEN is a static, unrevocable credential and is refused whenever TLS is on —
for anything real, issue a scoped token with ken token add.)
Status
In production. All eight knowledge-base MCP tools — kb_search, kb_get, kb_save,
kb_propose_enhancement, kb_flag_stale, kb_diff, kb_record_outcome,
kb_recent_context — are implemented, and the MCP server delivers its own usage
instructions to connecting agents (no prompt-pasting needed). The web UI is
complete: a home dashboard, search (with an all scope), a filterable Browse
grid, entry + history, the proposal queue with promote/reject, agent-token and
OAuth-connector management, the COMM console at /comm and the stations console at
/stations, first-run setup wizard, and live settings. It is a
themeable (dark/light) and multilingual (English, Spanish + French, with
drop-in translations) design system that makes zero external requests. An optional
OAuth 2.1 authorization server lets claude.ai add Ken as a custom connector.
Inter-session comms (COMM) and stations are core surfaces, on by default —
KEN_COMM_ENABLED=0 and KEN_STATION_ENABLED=0 opt out of either one
independently, and stations keep working with COMM off because a notebook and a
task list need no peers.
Embeddings, health/metrics, in-process ACME TLS, and self-extracting release
installers are built and tested.
Docs
- docs/DESIGN.md — architecture, locked decisions, rationale.
- docs/MCP-TOOLS.md — the AI-facing MCP tool contracts.
- docs/AI-INTEGRATION.md — how to make your AI use Ken (token strategy + the operating loop).
- docs/OAUTH.md — connect claude.ai as a custom connector (the optional OAuth server).
- docs/COMM.md — inter-session communication: let two AI sessions hand work to each other (core, on by default;
KEN_COMM_ENABLED=0opts out). - docs/STATIONS.md — stations: durable, human-named AI working identities with a notebook, a task list and a small file locker, which also become what COMM addresses so a peer relationship outlives the session that made it (core, on by default;
KEN_STATION_ENABLED=0opts out, independently of COMM — the notebook and task list work with COMM off). - docs/I18N.md — the multilingual UI: add a language or override any string at runtime (drop-in
.properties). - docs/INSTALL.md — install / deploy (self-extracting
.bin, systemd, TLS posture). - docs/MONITORING.md — health, metrics, and the Grafana/Prometheus bundle.
- docs/REMOTE-UPGRADE.md — the scoped, least-privilege remote-upgrade tooling.
- docs/BACKUP.md — backup & restore runbook.
- CHANGELOG.md — release history.
- COMPATIBILITY.md — what SemVer covers at 1.0 (stable MCP/CLI/env/token/schema surfaces); the
comm_*andstation_*tools stay outside it until the COMM v2 redesign lands. - migrations/ — the SQLite schema (source of truth;
0001_init.sql…0009_content_lang.sql).
Stack
Go single static binary · embedded SQLite (WAL) via ncruces/go-sqlite3 ·
FTS5 + trigram keyword search (embeddings optional) · MCP via the official
modelcontextprotocol/go-sdk · optional OAuth 2.1 authorization server ·
server-rendered web UI (html/template, no JS framework) — themeable dark/light
and multilingual (reloadable i18n), zero external requests · in-process ACME TLS.
Build & run (dev)
# requires Go 1.26.5+ on your PATH
go build ./...
go test ./...
# run with a demo entry seeded, and a dev token for the MCP endpoint
KEN_DEV_TOKEN=dev-secret go run ./cmd/ken --demo-seed
# then point an MCP client at http://localhost:8080/mcp with:
# Authorization: Bearer dev-secret
License
Ken is free and open source under the GNU Affero General Public License v3.0
(AGPL-3.0-only) — see LICENSE. In short: use, study, modify and share it
freely; and because Ken is a network service, the AGPL's §13 requires that if you
run a modified Ken as a service, you offer its users the corresponding source. A
running instance links to its source in the footer.
If you run a modified Ken, set KEN_SOURCE_URL to your own repository:
KEN_SOURCE_URL=https://example.org/you/ken-fork
That is what the footer link (and the login/setup pages) will point at, so your users
are offered your source — the code actually running — rather than this repository.
ken version prints the value in effect.
Copyright (C) 2026 Quest ICT.
Trademark: the AGPL grants rights to the code. It does not grant rights to the name "Ken" or the compass mark. Forks are welcome — please use your own name and logo so users can tell your build apart from this project.
Contributions are welcome under a Developer Certificate of Origin — see CONTRIBUTING.md.
SPDX-License-Identifier: AGPL-3.0-only
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
ken
command
Command ken runs the Ken knowledge-base service and its admin CLI.
|
Command ken runs the Ken knowledge-base service and its admin CLI. |
|
internal
|
|
|
clientip
Package clientip resolves the real client IP of an HTTP request.
|
Package clientip resolves the real client IP of an HTTP request. |
|
comm
Package comm owns the inter-session communication subsystem: authenticated message passing between AI sessions on the same or different machines (design decision D9; full contract in docs/COMM.md).
|
Package comm owns the inter-session communication subsystem: authenticated message passing between AI sessions on the same or different machines (design decision D9; full contract in docs/COMM.md). |
|
commserver
Package commserver exposes the inter-session communication subsystem (internal/comm) as an MCP endpoint, separate from the knowledge base's.
|
Package commserver exposes the inter-session communication subsystem (internal/comm) as an MCP endpoint, separate from the knowledge base's. |
|
embed
Package embed provides Ken's pluggable embedding SPI for semantic search.
|
Package embed provides Ken's pluggable embedding SPI for semantic search. |
|
health
Package health reports Ken's readiness as a small set of components (the data dir is writable, the database answers a ping), in the Actuator-style JSON shape {"status":"UP","components":{…}}.
|
Package health reports Ken's readiness as a small set of components (the data dir is writable, the database answers a ping), in the Actuator-style JSON shape {"status":"UP","components":{…}}. |
|
i18n
Package i18n gives Ken's human web UI runtime-reloadable, drop-in translations.
|
Package i18n gives Ken's human web UI runtime-reloadable, drop-in translations. |
|
i18n/i18nsync
command
Command i18nsync keeps the settings translations honest against the Go registry.
|
Command i18nsync keeps the settings translations honest against the Go registry. |
|
importer
Package importer parses the user's flat Markdown "memory" files (YAML frontmatter: name/description/metadata.type; body with **Why:** / **How to apply:** lines and [[wikilinks]]) into a neutral Memory shape for migration into ken.
|
Package importer parses the user's flat Markdown "memory" files (YAML frontmatter: name/description/metadata.type; body with **Why:** / **How to apply:** lines and [[wikilinks]]) into a neutral Memory shape for migration into ken. |
|
lang
Package lang detects the dominant human language of prose, for Ken's curation-language guardrail (a curator can only promote what they can read).
|
Package lang detects the dominant human language of prose, for Ken's curation-language guardrail (a curator can only promote what they can read). |
|
mcpserver
Package mcpserver builds Ken's Model Context Protocol server: the AI-facing interface (kb_search, kb_get, kb_propose_enhancement, kb_save, kb_flag_stale) over streamable HTTP, behind scoped bearer-token auth.
|
Package mcpserver builds Ken's Model Context Protocol server: the AI-facing interface (kb_search, kb_get, kb_propose_enhancement, kb_save, kb_flag_stale) over streamable HTTP, behind scoped bearer-token auth. |
|
metrics
Package metrics is Ken's tiny, dependency-free Prometheus exposition: a handful of atomic counters plus on-scrape gauge collectors, rendered as text/plain exposition format.
|
Package metrics is Ken's tiny, dependency-free Prometheus exposition: a handful of atomic counters plus on-scrape gauge collectors, rendered as text/plain exposition format. |
|
model
Package model holds Ken's domain types, shared across the store, MCP, and web layers.
|
Package model holds Ken's domain types, shared across the store, MCP, and web layers. |
|
oauth
Package oauth implements the stateless endpoints of Ken's optional OAuth 2.1 authorization server: discovery metadata (RFC 8414 + RFC 9728), dynamic client registration (RFC 7591), and the token endpoint (authorization_code + refresh_token, PKCE-S256).
|
Package oauth implements the stateless endpoints of Ken's optional OAuth 2.1 authorization server: discovery metadata (RFC 8414 + RFC 9728), dynamic client registration (RFC 7591), and the token endpoint (authorization_code + refresh_token, PKCE-S256). |
|
passwd
Package passwd hashes and verifies passwords with Argon2id, producing and consuming standard PHC strings ($argon2id$v=19$m=..,t=..,p=..$salt$hash).
|
Package passwd hashes and verifies passwords with Argon2id, producing and consuming standard PHC strings ($argon2id$v=19$m=..,t=..,p=..$salt$hash). |
|
ratelimit
Package ratelimit is Ken's application-layer abuse defense: a per-IP token-bucket "first filter" (allowlist bypass, auto-block for repeat offenders, 429 + Retry-After otherwise) plus a reusable per-key bucket the MCP layer uses for per-token limits.
|
Package ratelimit is Ken's application-layer abuse defense: a per-IP token-bucket "first filter" (allowlist bypass, auto-block for repeat offenders, 429 + Retry-After otherwise) plus a reusable per-key bucket the MCP layer uses for per-token limits. |
|
settings
Package settings holds Ken's operator-editable runtime configuration.
|
Package settings holds Ken's operator-editable runtime configuration. |
|
store
Package store owns Ken's embedded SQLite database: schema migrations plus the search/get queries.
|
Package store owns Ken's embedded SQLite database: schema migrations plus the search/get queries. |
|
version
Package version carries the build version of Ken and the location of its Corresponding Source (the AGPL-3.0 §13 network-interaction obligation).
|
Package version carries the build version of Ken and the location of its Corresponding Source (the AGPL-3.0 §13 network-interaction obligation). |
|
web
Package web serves Ken's human-facing UI: the first-run setup wizard, login (Argon2id + server-side session + CSRF + per-IP login guard), search/browse, and the proposal review queue (diff + promote/reject).
|
Package web serves Ken's human-facing UI: the first-run setup wizard, login (Argon2id + server-side session + CSRF + per-IP login guard), search/browse, and the proposal review queue (diff + promote/reject). |
|
webtls
Package webtls resolves and runs Ken's TLS posture.
|
Package webtls resolves and runs Ken's TLS posture. |
|
Package migrations embeds ken's SQL schema migrations.
|
Package migrations embeds ken's SQL schema migrations. |