Skip to content
Back to search

akb

AKB — Agent Knowledgebase. Organizational memory for AI agents: vault-scoped docs / tables / files unified by URI graph, served over MCP.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/dnotitia/akb with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/dnotitia/akb'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/dnotitia--akb/badge.svg)](/listings/dnotitia--akb)

HTML

<a href="/listings/dnotitia--akb"><img src="/api/listings/dnotitia--akb/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

New installations use **PostgreSQL Native** with a persisted installation identity and an explicit database bootstrap. Use a **new Compose project and never-used database**. Existing installations must follow the [pre-upgrade preservation procedure](docs/operations/native-installation.md#preserve-existing-configuration-before-changing-defaults) before using this version; changing a default does not migrate their data.

The recommended stack runs PostgreSQL with pgvector, MinIO, API, a separate worker, and frontend. One-shot services prepare the File bucket and Native authority before the application starts. Docker Compose 2.24.4+ is required. Configure an OpenAI-compatible embedding endpoint for dense search; pgvector and Qdrant degrade to BM25-only lexical search when embedding is unavailable.

MinIO uses a mirror with the original upstream server digest pinned after the Quay image removal. Local, evaluation, CI, and all-in-one builds use the same artifact; bucket bootstrap and all-in-one builds use the `mc` bundled in that server image.

# 1. Build this checkout's images. For a registry installation, use a backend
# image pinned as registry.example.com/akb-backend@sha256:... instead.
docker build -t akb-backend:native-local ./backend
docker compose -p my-native-install build frontend postgres
export AKB_NATIVE_IMAGE="$(docker image inspect akb-backend:native-local --format '{{.Id}}')"
export AKB_NATIVE_CONFIG_DIR="$PWD/config/native"

# 2. Prepare installation assets ONCE. Keep them and the original template.
mkdir -p "$AKB_NATIVE_CONFIG_DIR"
cp config/app.yaml.example "$AKB_NATIVE_CONFIG_DIR/template.yaml"
cp config/secret.yaml.example "$AKB_NATIVE_CONFIG_DIR/secret.yaml"
$EDITOR "$AKB_NATIVE_CONFIG_DIR/template.yaml" # provider and public URL settings
$EDITOR "$AKB_NATIVE_CONFIG_DIR/secret.yaml"   # credentials and independent secrets

docker run --rm -v "$AKB_NATIVE_CONFIG_DIR:/installation" \
  "$AKB_NATIVE_IMAGE" python -m app.cli generate-local-session-keyset \
  --output-dir /installation/local-session
docker run --rm -v "$AKB_NATIVE_CONFIG_DIR:/installation" \
  "$AKB_NATIVE_IMAGE" python -m app.cli prepare-native-config \
  --source /installation/template.yaml --secret /installation/secret.yaml \
  --output /installation/app.yaml --tenant-id my-installation --namespace akb \
  --image-digest "${AKB_NATIVE_IMAGE##*@}"

# 3. Use the same project, files and environment on every subsequent operation.
docker compose -p my-native-install \
  -f docker-compose.yaml -f docker-compose.native.yaml up -d --no-build

# 4. Provision the local recovery administrator with an operator-owned password.
docker compose -p my-native-install \
  -f docker-compose.yaml -f docker-compose.native.yaml \
  exec -T backend python -m app.cli provision-recovery-admin local \
  --username recovery-admin --email recovery-admin@example.com \
  --password-file - < /secure/operator/recovery-admin.password

open http://localhost:3000

To upgrade, update the checkout and repeat step 1 before step 3. `up --no-build` never builds, so it cannot pick up what the new checkout builds (`frontend`, `postgres`): a missing image makes it fail, and an old one keeps running. On the upgrade that turned PostgreSQL into a built image, skipping step 1 stops the API (`backend`) and then fails with `No such image: my-native-install-postgres:latest`, which leaves the API down.

The local image ID pins the locally built bytes; it is not a registry digest. For distributed installs, build/push first and use the registry digest for `AKB_NATIVE_IMAGE`. Keep the generated initializing image receipt unchanged when upgrading the workload image. Never regenerate identity or local-session keys on restart. On Linux, ensure the operator can read and back up assets created by the container (or run the preparer with the operator's UID/GID).

The generated `app.yaml` and companion `secret.yaml` are the single source of

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 24 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "akb-skillpack",
  3. "owner": {
  4. "name": "jylkim",
  5. "email": ""
  6. },
  7. "plugins": [
  8. {
  9. "name": "akb-claude-code",
  10. "source": "./plugins/claude/akb-claude-code",
  11. "description": "Bridge Claude Code's session lifecycle into AKB's agent-memory vault."
  12. },
  13. {
  14. "name": "akb-sessions",
  15. "source": "./plugins/claude/akb-sessions",
  16. "description": "Ingest coding sessions into an AKB vault as structured notes."
  17. },
  18. {
  19. "name": "akb-wiki",
  20. "source": "./plugins/claude/akb-wiki",
  21. "description": "LLM-wiki layer for AKB vaults — unified document ingest (any source) and hybrid search."
  22. }
  23. ]
  24. }
README.md · README · 793 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="docs/assets/akb-hero.png" alt="AKB — agents reading and writing into a permissioned knowledge vault of docs, tables, and files, linked by a URI graph" width="100%">
  3. </p>
  4. # AKB — Agent Knowledge Base
  5. > **Organizational memory for AI agents.** PostgreSQL-native knowledge base served
  6. > over the **Model Context Protocol (MCP)** — agents read and write directly
  7. > with hybrid semantic + keyword search, structured tables, files, and a URI
  8. > graph. Drop-in alternative to Confluence / Notion for Claude Code, Cursor,
  9. > Windsurf, and any MCP-aware agent.
  10. [![License: BSL 1.1](https://img.shields.io/badge/license-BUSL--1.1-blue.svg)](./LICENSE)
  11. [![npm: akb-mcp](https://img.shields.io/npm/v/akb-mcp.svg?label=npm%3A%20akb-mcp)](https://www.npmjs.com/package/akb-mcp)
  12. [![MCP](https://img.shields.io/badge/MCP-2026--07--28%20%2B%20legacy-orange.svg)](https://modelcontextprotocol.io)
  13. ## Works with
  14. Any agent client that speaks **MCP (Streamable HTTP or stdio)**:
  15. - **Claude Code** — CLI / VS Code / JetBrains
  16. - **Claude Desktop** — macOS / Windows
  17. - **Cursor**, **Windsurf**, **Cline**, **Continue** — via the
  18. [`akb-mcp`](https://www.npmjs.com/package/akb-mcp) stdio proxy
  19. - Custom agents — direct HTTP `POST /mcp/` with a Bearer token
  20. The stdio proxy accepts an explicit Personal Access Token (PAT). On an
  21. OAuth-enabled installation, run `npx akb-mcp login --url <mcp-url>` once
  22. before starting the host with a URL-only configuration. One credential covers
  23. MCP and the proxy's local file tools. [Configure the stdio proxy](packages/akb-mcp-client/README.md).
  24. For direct HTTP OAuth, configure the client and authorization server.
  25. [Configure direct HTTP OAuth](docs/mcp-clients/web-connectors.md).
  26. Product administrators can view server-observed calls by user, PAT and tool. [MCP monitoring](docs/operations/mcp-monitoring.md)
  27. ## MCP protocol compatibility
  28. AKB keeps one tool and authorization core behind two protocol adapters:
  29. | Surface | Modern | Legacy |
  30. |---|---|---|
  31. | Direct HTTP `/mcp/` | `2026-07-28` stateless `server/discover` and per-request `_meta` with `Mcp-Protocol-Version` / `Mcp-Method` (and `Mcp-Name` for named calls) | `2024-11-05`, `2025-03-26`, `2025-06-18`, `2025-11-25` initialize, stateless requests (no `Mcp-Session-Id` lifecycle) |
  32. | `akb-mcp` stdio proxy | `2026-07-28` discovery and per-request metadata | `2025-06-18` initialize |
  33. The proxy answers either handshake locally and normalizes backend calls to the
  34. modern stateless contract when available. For older backends without modern discovery, the proxy can fall back to
  35. legacy initialization and retain a session ID if that older server returns one.
  36. The current backend runs both adapters statelessly. A process
  37. cannot mix generations, and unsupported revisions or conflicting protocol
  38. evidence fail closed before a tool or local-file operation runs.
  39. ## Plugins
  40. Beyond raw MCP access, AKB ships ready-made **agent plugins** for **Claude Code**
  41. and **Codex** that wrap common vault workflows:
  42. - **akb-wiki** — ingest a source (local file, web URL, GitHub PR / release /
  43. commit, Confluence page, or Jira issue) into the vault as a structured
  44. document, and answer questions from the vault with grounded, cited synthesis
  45. (read-only).
  46. - **akb-sessions** — capture a coding session as structured notes: a session
  47. report plus follow-up tasks, learnings, ideas, and decisions.
  48. - **akb-claude-code** — a Claude Code lifecycle bridge: hooks anchor each
  49. session to your AKB memory vault, injecting preferences and recent learnings
  50. at the start and writing a recap at the end.
  51. ```
  52. /plugin marketplace add dnotitia/akb # Claude Code
  53. codex plugin marketplace add dnotitia/akb # Codex
  54. ```
  55. Install details and credentials: [`plugins/`](./plugins/skillpack-plugins.md).
  56. ## Try it live
  57. A public demo runs at **[akb-demo.agent.seahorse.dnotitia.ai](https://akb-demo.agent.seahorse.dnotitia.ai)**.
  58. Browse and search a small fictional-organization knowledge base — product docs,
  59. a company handbook, agent session notes, and an engineering wiki, cross-linked
  60. by the URI graph — right in your browser, no signup. To wire it into your own
  61. agent, sign up with any email (a throwaway address is fine) and point the
  62. [`akb-mcp`](https://www.npmjs.com/package/akb-mcp) proxy at
  63. `https://akb-demo.agent.seahorse.dnotitia.ai/mcp/`.
  64. > ⚠️ **Throwaway demo.** It is public, wiped and re-seeded weekly, and runs on
  65. > minimal resources with **no uptime, privacy, or data guarantees**. Don't put
  66. > anything real or sensitive in it — treat every write as public and ephemeral.
  67. > For real use, [self-host](#quick-start) with Docker Compose or Kubernetes.
  68. ## Why AKB
  69. Most knowledge tools are built for humans clicking through a UI. Agents need a
  70. different shape: structured documents, semantic + keyword search in one call,
  71. explicit relations, and full version history. AKB gives agents a single set of
  72. tools (`akb_put`, `akb_search`, `akb_browse`, `akb_relations`, …) over a
  73. PostgreSQL-native revision store and hybrid index. Explicit Bare Git installations
  74. remain supported for existing deployments.
  75. ## Retrieval quality
  76. Memory is only useful if the right note comes back. AKB's hybrid retrieval
  77. (dense + BM25, source-level dedup) was benchmarked on
  78. [LongMemEval](https://github.com/xiaowu0162/LongMemEval)-S — 500 long-context
  79. questions, ~50 chat sessions per question. **Recall@5 = 98.4%**, with no
  80. reranker in the loop.
  81. | System | R@5 | n | Reranker | Source |
  82. |---|---:|:---:|:---:|---|
  83. | **AKB hybrid** | **98.4%** | 500 | no | this repo |
  84. | MemPalace hybrid + rerank | 98.4% | 450 | yes | [MemPalace](https://github.com/mempalace/mempalace) |
  85. | gbrain hybrid | 97.6% | 500 | no | [gbrain-evals](https://github.com/garrytan/gbrain-evals) |
  86. | gbrain vector | 97.4% | 500 | no | gbrain-evals |
  87. Methodology, per-category breakdown, and a one-command reproducible harness
  88. live in [`eval/longmemeval/`](eval/longmemeval/). The embedding model differs
  89. across systems (AKB: `bge-m3@1024`), so read this as a stack-level comparison.
  90. ## Design philosophy
  91. **Core stays small; flexibility comes from extension, not built-in
  92. automation.** AKB does not ship its own consolidator, summariser, or
  93. "knowledge gardener" — instead every write records a structured event in the
  94. PostgreSQL outbox. When `redis_url` is configured, the publisher fans those
  95. events out to a Redis Stream (`akb:events`). Operators wire any external
  96. consumer (periodic synthesis bot, doc-rot reaper, weekly-digest agent, audit
  97. trail, …) on top, with no patches to the core. The base contract is a
  98. read/write store; opinions about *what to do with* the knowledge live outside.
  99. ## Architecture
  100. ```
  101. ┌──────────────────────────────────────────────────────────┐
  102. │ Access Layer │
  103. │ MCP Server │ REST API │ Web UI │
  104. ├──────────────────────────────────────────────────────────┤
  105. │ Core Services │
  106. │ Document (Put/Get) │ Search (Hybrid: dense+BM25) │
  107. │ Relations (graph) │ Session │ Publications │
  108. ├──────────────────────────────────────────────────────────┤
  109. │ Storage Layer │
  110. │ Native revisions │ PostgreSQL 16 (text + meta SoT)│
  111. │ │ Vector store (driver): │
  112. │ │ pgvector (default, PG)│
  113. │ │ qdrant (optional) │
  114. │ │ seahorse-cloud (managed) │
  115. │ │ seahorse-db (self-hosted)│
  116. │ │ seahorse-db-grpc(experimental)│
  117. └──────────────────────────────────────────────────────────┘
  118. ```
  119. PostgreSQL is the source of truth — chunk text + metadata + BM25 vocab.
  120. The vector store is a driver-pluggable derived index holding dense
  121. embeddings and corpus-side sparse vectors. Full vector-store loss is
  122. recoverable from PG by setting `chunks.vector_indexed_at = NULL` and
  123. letting the indexing worker re-populate.
  124. ## Key Concepts
  125. - **Vault** — The unit of access control and knowledge organization. Native
  126. revisions live in PostgreSQL; the legacy backend uses one bare Git repo per vault.
  127. - **Collection** — A directory inside a vault. Topical grouping of documents.
  128. - **Document** — Markdown + YAML frontmatter, optimised for agent read/write.
  129. - **Hybrid Search** — Dense (semantic) + BM25 (lexical) fused via RRF in one call.
  130. - **Relations** — `depends_on`, `related_to`, `implements` in frontmatter form an explicit knowledge graph.
  131. - **Vault isolation in `akb_sql`** — Enforced by PostgreSQL ACL. Each
  132. AKB user has a corresponding PG role (`akb_user_<uid>`) and each
  133. vault has three group roles (`akb_vault_<vid>_{reader,writer,admin}`).
  134. `akb_sql` runs the user's SQL inside a transaction with
  135. `SET LOCAL ROLE`; cross-vault references return PG `42501`
  136. directly. No application-side regex inspects user SQL for forbidden
  137. identifiers. See `docs/designs/pg-native-rbac/`.
  138. ## MCP Tools (selection)
  139. | Tool | Description |
  140. |------|-------------|
  141. | `akb_list_vaults` / `akb_create_vault` | Vault management |
  142. | `akb_put` / `akb_get` / `akb_update` / `akb_delete` | Document CRUD (revision + indexing) |
  143. | `akb_put_file` / `akb_get_file` / `akb_update_file` / `akb_delete_file` | File attachments — proxy-side (requires local filesystem) |
  144. | `akb_put_image` / `akb_discard_image` | Validated inline Markdown images — proxy-side in `akb-mcp` 2.2+ |
  145. | `akb_create_table` / `akb_alter_table` / `akb_drop_table` / `akb_sql` | Tabular content — per-doc tables + SQL |
  146. | `akb_browse` | Tree traversal (collection → docs) |
  147. | `akb_search` / `akb_grep` | Hybrid search (dense + BM25) / literal grep |
  148. | `akb_drill_down` | Section-level retrieval |
  149. | `akb_relations` / `akb_link` / `akb_unlink` / `akb_graph` | Knowledge graph |
  150. | `akb_edit` / `akb_diff` / `akb_history` | In-place edit, diff, revision history |
  151. | `akb_grant` / `akb_revoke` / `akb_set_public` | Permission boundaries — per-user, per-org, public |
  152. | `akb_publish` / `akb_unpublish` | Public publication |
  153. Agent memory and session lifecycle are not MCP tools — they live on
  154. the dedicated `/api/v1/agent-sessions` REST surface, driven by AKB
  155. lifecycle plugins (`akb-claude-code`, `akb-cursor`, …) that hook into
  156. the agent's own SessionStart / PreCompact / SessionEnd events. As an
  157. agent, your own memory vault (`agent-memory-{username}`) is browsable
  158. through the standard `akb_search` / `akb_browse` / `akb_get` tools
  159. exactly like any other vault.
  160. The full tool catalogue is exposed via `akb_help()` from any MCP client.
  161. ### Inline document images from MCP
  162. Inline images are hidden document attachments, not browsable Files. Upload a
  163. local PNG, JPEG, GIF, or WebP (maximum 10 MiB), then insert the returned
  164. Markdown without reconstructing its asset URL:
  165. ```text
  166. image = akb_put_image(
  167. parent="akb://eng/coll/specs",
  168. file_path="/workspace/architecture.png",
  169. alt_text="Request processing architecture")
  170. akb_put(
  171. parent="akb://eng/coll/specs",
  172. title="Request Processing",
  173. content="# Architecture\n\n" + image.markdown)
  174. ```
  175. For an existing document, use `akb_get` followed by a targeted
  176. `akb_edit(base_commit=...)`. Do not pass only the image fragment to
  177. `akb_update(content=...)`, which replaces the complete body. Image bytes are
  178. immutable: replacing an image means uploading a new one and editing the
  179. Markdown reference. Remove an image by deleting its Markdown expression; use
  180. `akb_discard_image` only for an upload that never reached a successful document
  181. commit. Run `akb_help(topic="images")` for retention and publication behavior.
  182. The image tools require both the matching backend release and `akb-mcp` 2.2 or
  183. newer. For upgrades, deploy the backend first, then publish/install the proxy
  184. and restart existing MCP processes so they load the updated tool list.
  185. ## Document Format
  186. Every vault resource has a location-aware AKB URI — the canonical handle
  187. used by every tool and stored in relations. As of 0.3.0:
  188. ```
  189. akb://{vault} vault root (browse target)
  190. akb://{vault}/coll/{coll_path} collection (browse target)
  191. akb://{vault}[/coll/{coll_path}]/doc/{filename} document
  192. akb://{vault}[/coll/{coll_path}]/table/{name} table
  193. akb://{vault}[/coll/{coll_path}]/file/{uuid} file
  194. ```
  195. The `/coll/{coll_path}` segment is omitted for resources at the vault
  196. root. Walking up a URI to its parent collection is a pure string
  197. operation — paste the parent into `akb_browse(uri=...)` to list
  198. siblings without an extra lookup.
  199. For large Vaults, start with `akb_browse(uri=..., depth=0, page_size=100)`
  200. and follow `next_cursor` until `complete=true`, or drill into a Collection.
  201. See [bounded navigation and literal-search scope limits](docs/operations/large-vault-navigation.md)
  202. for paging, partial results and protective grep errors.
  203. ```yaml
  204. ---
  205. title: "Payment API v2 migration plan"
  206. type: plan # note | report | decision | spec | plan | session | task | reference
  207. status: active # draft | active | archived | superseded
  208. tags: [payments, api]
  209. domain: engineering
  210. summary: "REST → gRPC transition plan."
  211. depends_on: ["akb://eng/coll/specs/doc/payment-api-v2.md"]
  212. related_to: ["akb://eng/coll/meetings/doc/2026-05-01-payments.md"]
  213. ---
  214. # Payment API v2 migration plan
  215. ...
  216. ```
  217. ### Open Knowledge Format (OKF) compatible
  218. With the explicit Bare Git backend, a vault is stored as a git tree of
  219. `.md` + YAML-frontmatter files whose
  220. identity is the path — the same model as Google Cloud's
  221. [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog)
  222. (OKF v0.1), which AKB independently arrived at before the spec existed.
  223. AKB-authored bundles satisfy all three OKF MUST rules. Server-side
  224. `akb_export({"vault": "<vault>", "format": "okf"})` and authenticated
  225. `GET /api/v1/vaults/{vault}/export?format=okf` support both PostgreSQL Native
  226. and Bare Git through the document service. Bundles contain documents plus
  227. tables/files represented as concept documents.
  228. The offline CLI below reads an existing Bare Git worktree; it does not read
  229. Native storage. Run it from `backend/`:
  230. ```bash
  231. cd backend
  232. uv run python -m app.cli okf-export --from-git /data/vaults/_worktrees/<vault> \
  233. --vault <vault> --out ./okf-out/
  234. uv run python -m app.cli okf-validate ./okf-out/
  235. ```
  236. OKF and AKB are complementary — OKF standardizes *how knowledge is written
  237. down*; AKB stores, versions, searches, governs, and serves it to agents. See
  238. [`okf/`](okf/) for the mapping and a sample bundle.
  239. ## Guides
  240. Task-oriented guides for teams evaluating or adopting an agent knowledge layer:
  241. - [Sharing one agent memory across Claude Code, Cursor, and other MCP clients](docs/guides/shared-agent-memory-across-mcp-clients.md)
  242. - [Evaluating retrieval claims for an agent knowledge layer](docs/guides/evaluating-retrieval-claims.md)
  243. - [Keeping document structure in retrieval: heading-aware chunks and section reads](docs/guides/structure-aware-chunking-and-section-reads.md)
  244. - [Self-hosting AKB: license terms, seat counting, and checks before you commit](docs/guides/self-hosting-license-and-seats.md)
  245. - [Applying permissions at query time when agents search shared knowledge](docs/guides/query-time-permissions-for-agent-search.md)
  246. - [Keeping a record of what coding agents decided](docs/guides/recording-coding-agent-decisions.md)
  247. - [Keeping search current when documents and embedding models change](docs/guides/keeping-embeddings-current.md)
  248. - [Adding a knowledge layer to an existing agent stack](docs/guides/adding-a-knowledge-layer-to-an-existing-agent-stack.md)
  249. - [Adding a new department without rebuilding the setup](docs/guides/adding-a-new-department-without-a-rebuild.md)
  250. - [Exporting a vault to the Open Knowledge Format](docs/guides/exporting-a-vault-to-open-knowledge-format.md)
  251. - [Keeping model calls inside your network](docs/guides/keeping-model-calls-inside-your-network.md)
  252. - [Moving agent memory from one laptop to a team-wide store](docs/guides/moving-agent-memory-to-a-team-store.md)
  253. - [Moving Markdown notes into a searchable store](docs/guides/moving-markdown-notes-into-a-searchable-store.md)
  254. - [Why a vector store alone is a weak agent memory](docs/guides/why-a-vector-store-alone-is-a-weak-agent-memory.md)
  255. - [Choosing what to ingest into a knowledge base](docs/guides/choosing-what-to-ingest.md)
  256. - [Combining search, grep, relations and SQL for agent lookups](docs/guides/combining-search-grep-relations-and-sql.md)
  257. - [Connectors or your own ingestion](docs/guides/connectors-or-your-own-ingestion.md)
  258. - [Keeping ingested copies linked to their source](docs/guides/keeping-ingested-copies-linked-to-their-source.md)
  259. - [Reaching people in the tools they already use](docs/guides/reaching-people-in-the-tools-they-already-use.md)
  260. - [Running agent knowledge alongside a wiki](docs/guides/running-agent-knowledge-alongside-a-wiki.md)
  261. - [Separating teams and agents with vault permissions](docs/guides/separating-teams-and-agents-with-vault-permissions.md)
  262. - [Building curation on change events](docs/guides/building-curation-on-change-events.md)
  263. - [Citing the exact source behind an answer](docs/guides/citing-the-exact-source-behind-an-answer.md)
  264. - [Finding duplicate and outdated documents](docs/guides/finding-duplicate-and-outdated-documents.md)
  265. - [Reconciling conflicting names across systems](docs/guides/reconciling-conflicting-names-across-systems.md)
  266. - [Reviewing agent writes before they go live](docs/guides/reviewing-agent-writes-before-they-go-live.md)
  267. - [Rolling back a document to an earlier version](docs/guides/rolling-back-a-document-to-an-earlier-version.md)
  268. - [Running a shared vocabulary as living documents](docs/guides/running-a-shared-vocabulary-as-living-documents.md)
  269. ## Quick Start
  270. New installations use **PostgreSQL Native** with a persisted installation identity
  271. and an explicit database bootstrap. Use a **new Compose project and never-used
  272. database**. Existing installations must follow the
  273. [pre-upgrade preservation procedure](docs/operations/native-installation.md#preserve-existing-configuration-before-changing-defaults)
  274. before using this version; changing a default does not migrate their data.
  275. The recommended stack runs PostgreSQL with pgvector, MinIO, API, a separate
  276. worker, and frontend. One-shot services prepare the File bucket and Native
  277. authority before the application starts. Docker Compose 2.24.4+ is required.
  278. Configure an OpenAI-compatible embedding endpoint for dense search; pgvector
  279. and Qdrant degrade to BM25-only lexical search when embedding is unavailable.
  280. MinIO uses a mirror with the original upstream server digest pinned after
  281. the Quay image removal.
  282. Local, evaluation, CI, and all-in-one builds use the same artifact; bucket
  283. bootstrap and all-in-one builds use the `mc` bundled in that server image.
  284. ```bash
  285. # 1. Build this checkout's images. For a registry installation, use a backend
  286. # image pinned as registry.example.com/akb-backend@sha256:... instead.
  287. docker build -t akb-backend:native-local ./backend
  288. docker compose -p my-native-install build frontend postgres
  289. export AKB_NATIVE_IMAGE="$(docker image inspect akb-backend:native-local --format '{{.Id}}')"
  290. export AKB_NATIVE_CONFIG_DIR="$PWD/config/native"
  291. # 2. Prepare installation assets ONCE. Keep them and the original template.
  292. mkdir -p "$AKB_NATIVE_CONFIG_DIR"
  293. cp config/app.yaml.example "$AKB_NATIVE_CONFIG_DIR/template.yaml"
  294. cp config/secret.yaml.example "$AKB_NATIVE_CONFIG_DIR/secret.yaml"
  295. $EDITOR "$AKB_NATIVE_CONFIG_DIR/template.yaml" # provider and public URL settings
  296. $EDITOR "$AKB_NATIVE_CONFIG_DIR/secret.yaml" # credentials and independent secrets
  297. docker run --rm -v "$AKB_NATIVE_CONFIG_DIR:/installation" \
  298. "$AKB_NATIVE_IMAGE" python -m app.cli generate-local-session-keyset \
  299. --output-dir /installation/local-session
  300. docker run --rm -v "$AKB_NATIVE_CONFIG_DIR:/installation" \
  301. "$AKB_NATIVE_IMAGE" python -m app.cli prepare-native-config \
  302. --source /installation/template.yaml --secret /installation/secret.yaml \
  303. --output /installation/app.yaml --tenant-id my-installation --namespace akb \
  304. --image-digest "${AKB_NATIVE_IMAGE##*@}"
  305. # 3. Use the same project, files and environment on every subsequent operation.
  306. docker compose -p my-native-install \
  307. -f docker-compose.yaml -f docker-compose.native.yaml up -d --no-build
  308. # 4. Provision the local recovery administrator with an operator-owned password.
  309. docker compose -p my-native-install \
  310. -f docker-compose.yaml -f docker-compose.native.yaml \
  311. exec -T backend python -m app.cli provision-recovery-admin local \
  312. --username recovery-admin --email recovery-admin@example.com \
  313. --password-file - < /secure/operator/recovery-admin.password
  314. open http://localhost:3000
  315. ```
  316. To upgrade, update the checkout and repeat step 1 before step 3. `up --no-build`
  317. never builds, so it cannot pick up what the new checkout builds (`frontend`,
  318. `postgres`): a missing image makes it fail, and an old one keeps running. On the
  319. upgrade that turned PostgreSQL into a built image, skipping step 1 stops the API
  320. (`backend`) and then fails with `No such image: my-native-install-postgres:latest`,
  321. which leaves the API down.
  322. The local image ID pins the locally built bytes; it is not a registry digest.
  323. For distributed installs, build/push first and use the registry digest for
  324. `AKB_NATIVE_IMAGE`. Keep the generated initializing image receipt unchanged
  325. when upgrading the workload image. Never regenerate identity or local-session
  326. keys on restart. On Linux, ensure the operator can read and back up assets
  327. created by the container (or run the preparer with the operator's UID/GID).
  328. The generated `app.yaml` and companion `secret.yaml` are the single source of
  329. application configuration and are mounted read-only at `/etc/akb`.
  330. `AKB_PROCESS_ROLE=all|api|worker` only selects process composition;
  331. `AKB_TOKENIZER_PROCESSES=1..4` can reduce tokenizer concurrency. Revision
  332. selection is not an environment-variable switch.
  333. See the [Native installation guide](docs/operations/native-installation.md)
  334. for image upgrades, bootstrap recovery and Kubernetes. The
  335. [Compose guide](deploy/compose/README.md) preserves the explicit Bare Git
  336. upgrade path. Helm, all-in-one and standalone SSO remain **legacy Bare Git
  337. compatibility paths** in this release. Native does not support document
  338. templates or external Git imports; its discovery and API reject those
  339. capabilities. Existing migration/history/diff/activity compatibility remains.
  340. Ordinary registration always creates a non-admin account, including on an
  341. empty database. Administrator bootstrap is available only through the
  342. operator CLI; there is no unauthenticated HTTP bootstrap endpoint. The CLI
  343. profile must match `auth_mode`:
  344. ```bash
  345. # Local: have AKB generate the password only when an operator-owned output
  346. # file is explicitly requested. A new file is created with mode 0600 and the
  347. # password is not written to stdout, stderr, logs, or application config.
  348. python -m app.cli provision-recovery-admin local \
  349. --username recovery-admin --email recovery-admin@example.com \
  350. --generate-password-file /secure/operator/recovery-admin.password
  351. # SSO: pre-bind the product administrator to the exact external identity.
  352. # Username and email are snapshots; issuer + subject are the identity key.
  353. python -m app.cli provision-recovery-admin sso \
  354. --username recovery-admin --email recovery-admin@example.com \
  355. --issuer https://issuer.example.com/realms/akb \
  356. --subject exact-provider-subject
  357. ```
  358. The same exact identity is idempotent. A different designation, an existing
  359. username/email, or an already-bound external identity fails closed. The SSO
  360. command stores no usable local password and does not contact the identity
  361. provider. Generated output files are create-only and never overwritten; for a
  362. retry after the file exists, pass that file back with `--password-file`.
  363. The two local forms differ in one further way. `--generate-password-file` is
  364. AKB producing a credential and handing it over, so the account it creates owes
  365. a replacement for it: the first session that credential opens can reach the
  366. password change and nothing else, exactly as a password reset behaves.
  367. `--password-file` installs a value the caller already holds — AKB delivers it
  368. to nobody — so it arms nothing, and an installation that signs in as this
  369. account to bootstrap its own service identity keeps working. To force a
  370. replacement for a credential supplied that way, rotate it afterwards with the
  371. command below; rotation always leaves the account owing a change.
  372. If that credential later leaks, is lost, or has to be taken back, rotate it
  373. rather than reprovisioning the account:
  374. ```bash
  375. # Break-glass: replace the credential and print the new one once. Nothing
  376. # stores or logs the value, and the machine-readable report omits it.
  377. python -m app.cli issue-recovery-admin-credential \
  378. --expected-username recovery-admin \
  379. --expected-email recovery-admin@example.com
  380. ```
  381. Rotation names the account it expects and refuses any mismatch, so it cannot
  382. act on the wrong one. The credential it replaces stops working immediately,
  383. including one currently in use, and sessions held before the rotation are
  384. revoked — both are what a compromise response requires. The same operation is
  385. available at `POST /admin/recovery-admin/issue-credential`, which requires an
  386. independent service-administrator token rather than a human session. Rotation
  387. is not available in `sso` mode: the identity provider holds the credential,
  388. and nothing in a running AKB can replace it.
  389. Open `/admin` for the separate product-administration surface. In `local`
  390. mode it accepts the provisioned local administrator and returns the same
  391. `local-session-rs256-v2` profile used by local human authentication, but it
  392. refuses non-admin accounts. In `sso` mode local credentials are absent:
  393. `/admin` uses a dedicated confidential `akb-admin` Keycloak client with PKCE
  394. and nonce, then accepts only the exact pre-bound `(issuer, subject)` whose AKB
  395. account is still active and `is_admin=true`.
  396. In SSO mode the same `/admin` surface can configure a built-in upstream IdP,
  397. save it disabled, inspect its exact broker redirect URI, and enable or disable
  398. its ordinary-login option without redeploying AKB. The option becomes a usable
  399. button only when the server-side browser-session capability is ready. Client
  400. secrets are write-only, and an enabled provider must be disabled before
  401. reconfiguration.
  402. See the [SSO provider guide](./docs/sso/README.md), the standards-based
  403. [generic OIDC integration](./docs/sso/providers/oidc.md), and the stricter
  404. [Keycloak OIDC reference](./docs/sso/providers/keycloak-oidc.md). Existing
  405. Kubernetes installations should also follow the
  406. [local-to-SSO cutover runbook](./docs/sso/kubernetes-cutover.md) instead of
  407. treating `auth_mode` as a rolling one-line configuration change.
  408. The dedicated admin callback stores no Keycloak access, refresh, or ID token.
  409. It creates a short-lived opaque HttpOnly admin cookie plus a CSRF token;
  410. PostgreSQL stores only their hashes plus the exact identity snapshot, and
  411. rechecks the account, unchanged external binding, and admin flag on every
  412. request. Its one-time OIDC state is also bound to a short-lived HttpOnly cookie
  413. so a callback copied into another browser fails before token exchange.
  414. Configure `keycloak_admin_client_secret`, register
  415. `<public_base_url>/api/v1/admin/auth/keycloak/callback` and
  416. `<public_base_url>/admin` in the dedicated client, and keep the admin client ID
  417. out of every API/MCP resource-client path. Browser-facing AKB and Keycloak URLs
  418. must use HTTPS outside the explicit loopback development exception.
  419. Ordinary SSO login uses the separate `akb-web` client. The browser receives
  420. only an opaque HttpOnly AKB session plus a readable CSRF value; SSO does not
  421. mint an AKB user JWT. AKB encrypts the Keycloak refresh/ID token set with the
  422. independent `sso_browser_session_encryption_key` and never persists an access
  423. token. The client must map Keycloak's `identity_provider` user-session note
  424. into both ID and access tokens with `oidc-usersessionmodel-note-mapper`; AKB
  425. binds that signed broker alias to the selected enabled provider on callback
  426. and every refresh. Production HTTPS cookies use the browser-enforced `__Host-` prefix,
  427. `Secure`, no `Domain`, and `Path=/`; loopback HTTP uses isolated development
  428. names. Generate the key as 32 random bytes encoded with unpadded base64url and
  429. keep it stable across restarts. See the [Keycloak boundary](./docs/designs/keycloak-oidc/00-overview.md)
  430. for refresh, logout, and back-channel revocation details.
  431. ### Local JWT migration and rotation
  432. Local login issues only the versioned `local-session-rs256-v2` profile:
  433. RS256 with an installation-owned RSA-3072 key, an RFC 7638 `kid`, exact
  434. deployment issuer/audience, `jti`, and a public-only JWKS at
  435. `GET /api/v1/auth/jwks`. AKB never chooses a verifier from an untrusted token
  436. `alg` header. Upgrading from an HS256 release is an intentional forced-login
  437. boundary: generate and persist the v2 keyset before rollout, set
  438. `jwt_algorithm: RS256`, and restart all backends together. Existing HS256 user
  439. sessions then receive 401 and must sign in again; PATs and service keys are not
  440. revoked. Internal HMAC capabilities use `system_hmac_secret`. An old
  441. `jwt_secret` key now fails startup. If `system_hmac_secret` is already set,
  442. delete `jwt_secret` and keep `system_hmac_secret` as it is; otherwise rename
  443. `jwt_secret` to `system_hmac_secret` with the value unchanged. Either way the
  444. secret in effect stays the same, so links and cursors signed with it keep
  445. working.
  446. For routine v2 key rotation, generate a new directory while retaining the
  447. current public JWKS, publish the new immutable Secret/config revision, and
  448. roll every backend to that exact pair:
  449. ```bash
  450. cd backend
  451. uv run python -m app.cli generate-local-session-keyset \
  452. --output-dir /secure/akb/local-session-next \
  453. --retain-jwks /secure/akb/local-session-current/jwks.json
  454. ```
  455. Keep a retained public key for at least `jwt_expire_hours` plus rollout skew,
  456. then remove it in a later coordinated keyset revision. Restoring the previous
  457. private/JWKS pair is the rollback; never overwrite key files in place.
  458. ### Vector store (driver-pluggable)
  459. See [BM25 statistics and VChord-only deployments](docs/vector-store-bm25-statistics.md)
  460. for weight conventions, external statistics consumers and posting rollback requirements.
  461. Hybrid search (dense + BM25 sparse, RRF-fused) runs through a driver
  462. interface. Five drivers ship; pick at config time:
  463. - **`pgvector`** (default) — uses the same Postgres container that holds
  464. application data. The install paths build that container's image from
  465. `deploy/postgres/Dockerfile`: pgvector plus the `vchord_bm25` BM25 index,
  466. which gives a new database the default `vchord` sparse shape. The driver
  467. creates a separate `vector_index` schema, so the main `chunks` table stays
  468. plain PostgreSQL. RRF fusion runs application-side. No external service to
  469. operate.
  470. - **`qdrant`** — runs a separate Qdrant container; native RRF via the
  471. Query API. Useful when you already operate Qdrant or want to scale
  472. the vector store independently of Postgres.
  473. - **`seahorse-cloud`** — points at a managed [Seahorse Cloud][shc] table
  474. over its BFF management API + per-table data-plane host (Bearer auth).
  475. No infrastructure to run on your side; you provision a table in the
  476. Seahorse console (or let the driver auto-create one) and AKB stores
  477. its chunks there. Native RRF, server-side BM25. See
  478. [`docs/vector-store-seahorse.md`](./docs/vector-store-seahorse.md)
  479. for the end-to-end setup walkthrough (sign-up → token → schema →
  480. config).
  481. - **`seahorse-db`** — points at a **self-hosted SeahorseDB** cluster via
  482. its Coral coordinator HTTP API. You run Coral + Writer + Reader(s) +
  483. Redis + Kafka + a sparse-embedding server yourself (the SeahorseDB
  484. monorepo's `deploy/docker-compose.yml` brings up a minimal single-box
  485. stack). Native dense+sparse hybrid. Unlike the other drivers it does
  486. **not** support BM25-only fallback when the embed API is down (its
  487. sparse path is server-side and structurally coupled to a live embed
  488. step) — keep an embedding endpoint reachable for this driver.
  489. - **`seahorse-db-grpc`** *(experimental)* — same Coral coordinator as
  490. `seahorse-db`, same `seahorsedb_*` settings, but talks gRPC instead
  491. of REST/JSONL. Coral merges axum + tonic onto a single listener so
  492. the port doesn't change; only the wire format does. Trades the JSON
  493. parsing path (and a class of foot-guns like INT64 sign mismatch and
  494. Arrow JSON decoder edge cases) for typed protobuf messages and an
  495. Arrow IPC streaming result. Prefer the REST driver for production
  496. until the gRPC variant clears its own QPS / recall benchmark. Same
  497. CRUD parity with REST (passes the same 25-scenario hybrid e2e), but
  498. it has not yet had the production-scale exposure the REST driver
  499. has.
  500. [shc]: https://console.seahorse.dnotitia.ai
  501. Switching drivers is a config edit (no schema migration on the main DB):
  502. ```bash
  503. # Default flow targets pgvector.
  504. docker compose up
  505. # Qdrant:
  506. docker compose -f docker-compose.yaml -f docker-compose.qdrant.yaml up
  507. $EDITOR config/app.yaml # vector_store_driver: qdrant
  508. # vector_url: http://qdrant:6333
  509. # Seahorse Cloud (managed; full guide in docs/vector-store-seahorse.md):
  510. docker compose up # no extra container needed
  511. $EDITOR config/app.yaml # vector_store_driver: seahorse-cloud
  512. # seahorse_cloud_tenant_uuid: <your tenant>
  513. # seahorse_cloud_table_name: <your table>
  514. $EDITOR config/secret.yaml # seahorse_cloud_token: shsk_<...>
  515. # SeahorseDB (self-hosted cluster reached via the Coral coordinator):
  516. docker compose up # run the SeahorseDB stack separately
  517. $EDITOR config/app.yaml # vector_store_driver: seahorse-db
  518. # seahorsedb_coordinator_url: http://localhost:3003
  519. # seahorsedb_table_name: akb_chunks
  520. ```
  521. Embedding model + dimensions are also fully pluggable via
  522. `embed_base_url` / `embed_model` / `embed_dimensions` — the codebase has
  523. no hard-coded model. For pgvector with HNSW, keep `embed_dimensions ≤ 2000`
  524. (or 4000 with `halfvec`); larger models fall back to exact scan.
  525. Qdrant / Seahorse (cloud or db) have no such limit (Qdrant up to 65536,
  526. Seahorse up to its table-defined dim).
  527. ### LLM features (optional)
  528. LLM is only used by the `metadata_worker` to auto-tag documents imported via
  529. external git mirroring. Core CRUD/search works without it. To enable, set
  530. `llm_base_url` / `llm_model` in `app.yaml` and `llm_api_key` in `secret.yaml`.
  531. Standalone deployments default to `model_api_governance_mode: external_metering`
  532. and may point embedding, chat, and rerank at any compatible provider. A managed
  533. control plane can instead set `platform_hard` plus an exact
  534. `platform_gateway_base_url`. In that mode AKB fails startup if an active model
  535. route points anywhere else or lacks a credential, and every model call carries
  536. a caller-generated `Idempotency-Key` for durable gateway reservation/settlement.
  537. Gateway policy or budget denials are never fanned out into per-item retries.
  538. ### Event fanout (optional)
  539. The PG `events` outbox is always written. Set `redis_url` in `app.yaml` to
  540. have the `events_publisher` worker drain the outbox to a Redis Stream
  541. (`akb:events`) so external services can subscribe via `XREAD` / consumer
  542. groups. Leave blank to disable Redis fanout; the authenticated
  543. `GET /api/v1/events/{vault}` SSE tail reads the same PG outbox. Native document
  544. writes participate in this outbox at the authority transaction boundary.
  545. See the [change-event contract](docs/operations/change-events.md) for supported
  546. File/document actions, move identity, retry semantics and consumer recovery.
  547. ### Audit log (optional)
  548. Off by default. Set `audit.enabled: true` in `app.yaml` to emit a structured,
  549. append-only, **hash-chained** JSON-lines audit log at the MCP dispatch
  550. chokepoint — every read, write, and auth denial, uniformly. AKB is a
  551. **producer only**: it does not store, query, or retain audit data; your SIEM
  552. (Splunk/QRadar/Elastic) scrapes the stream and owns retention under its own
  553. compliance regime. Each line carries a monotonic `seq` plus
  554. `sha256(prev ‖ line)`, so the chain can be verified for dropped or altered
  555. lines and re-seeds from disk across restarts. Optionally hand the daily
  556. rolled file off to a **WORM** object-storage bucket (`audit.bucket` —
  557. provision with Object Lock and a write-only key for a true immutable trail);
  558. the local buffer is pruned only after a confirmed upload. Capture is
  559. best-effort and never raises into the serving path. See
  560. `config/app.yaml.example` for the full `audit:` block.
  561. ### Production deployment
  562. For Kubernetes, start with the
  563. [`deployment guide`](./deploy/k8s/README.md). AKB provides standalone local and
  564. standalone-SSO resource sets through both Helm and Kustomize.
  565. - Use the dependency-free [`AKB Helm chart`](./deploy/helm/akb/README.md) for a
  566. standard `helm upgrade --install` workflow.
  567. - Use [`deploy/k8s`](./deploy/k8s/README.md) for the standalone Kustomization or
  568. `deploy/k8s/standalone-sso` for an installation-owned Keycloak stack.
  569. - Both paths consume pre-existing, operator-owned Kubernetes Secrets. AKB does
  570. not install or operate a credential service or synchronization controller.
  571. Real hostnames, registries, storage classes, TLS issuers, and provider settings
  572. belong in Helm values or an operator-owned Kustomize overlay; do not commit
  573. production credentials to this repository.
  574. ## Project Structure
  575. ```
  576. akb/
  577. ├── backend/ # Python 3.14 / FastAPI / asyncpg / GitPython
  578. │ ├── app/
  579. │ │ ├── api/routes/ # REST endpoints
  580. │ │ ├── services/ # Business logic + workers
  581. │ │ └── db/ # PostgreSQL schema + migrations
  582. │ ├── mcp_server/ # Streamable HTTP MCP server
  583. │ └── tests/ # E2E shell tests
  584. ├── frontend/ # React 19 + TypeScript + Vite + Tailwind
  585. ├── packages/
  586. │ ├── akb-client/ # REST SDK boundary (npm: @akb/client)
  587. │ └── akb-mcp-client/ # stdio ↔ HTTP MCP proxy (npm: akb-mcp)
  588. ├── agents/ # Reference Python agent runtime (think/act loop over MCP)
  589. ├── plugins/ # Claude Code / Codex agent plugins (ingest, query, session capture, lifecycle)
  590. ├── templates/ # Doc templates (ADR, PRD, runbook, …) and vault profiles
  591. ├── okf/ # Open Knowledge Format interop: positioning + sample bundle
  592. ├── design-system/ # Frontend design system docs
  593. ├── config/
  594. │ ├── app.yaml.example # Non-secret runtime settings
  595. │ └── secret.yaml.example # API keys, passwords (gitignored when not .example)
  596. ├── deploy/
  597. │ ├── all-in-one/ # Single-container demo image
  598. │ ├── helm/
  599. │ │ └── akb/ # AKB chart with local and standalone-SSO profiles
  600. │ └── k8s/
  601. │ ├── *.yaml # Standalone AKB + PostgreSQL resources
  602. │ └── standalone-sso/ # Standalone plus owned Keycloak and its database
  603. └── docker-compose.yaml # Local stack (PG + MinIO + API + worker + frontend)
  604. ```
  605. ## Tech Stack
  606. - **Backend**: Python 3.14, FastAPI, Uvicorn, asyncpg, GitPython, MCP SDK
  607. - **Database**: PostgreSQL 16 (main DB needs no extension; the same
  608. pgvector/pgvector image hosts the optional vector_index schema)
  609. - **Vector store**: driver-pluggable (pgvector default; Qdrant,
  610. Seahorse Cloud, or self-hosted SeahorseDB optional — hybrid dense +
  611. BM25 sparse, RRF fusion; BM25-only fallback when embed is down)
  612. - **Event stream** (optional): PG `events` outbox + Redis Streams fanout
  613. - **Audit log** (optional): hash-chained append-only JSONL at the MCP
  614. dispatch point + optional WORM S3 handoff; producer-only (SIEM owns retention)
  615. - **Frontend**: React 19, TypeScript, Vite, Tailwind CSS v4, Radix UI
  616. - **Auth**: local RS256 sessions or Keycloak SSO, plus Personal Access Tokens
  617. (PATs) for API and MCP access
  618. - **MCP**: Streamable HTTP (backend) + stdio proxy (`akb-mcp` on npm)
  619. ## Versioning
  620. AKB follows [SemVer](https://semver.org/). The backend product version lives in
  621. `backend/pyproject.toml` (`[project].version`). A coordinated release uses
  622. `scripts/bump-version.sh <x.y.z>` to update it together with
  623. `frontend/package.json`. With image building enabled, each
  624. `deploy/k8s/deploy.sh` run tags the Docker images with both the
  625. explicit backend version (`:${VERSION}`) and `:latest`, so historical builds
  626. remain pullable for rollback.
  627. `packages/akb-mcp-client` (the `akb-mcp` npm proxy) follows its own npm
  628. semver lifecycle and is **not** tied to the product version.
  629. ## License
  630. The AKB backend, frontend, and deployment manifests are licensed under
  631. the [Business Source License 1.1](./LICENSE) — source-available, with
  632. an Additional Use Grant that permits production use (commercial or
  633. non-commercial) up to a seat-count threshold, automatically converting
  634. to **Apache License 2.0** four years after each version's first public
  635. release.
  636. The npm `akb-mcp` proxy (`packages/akb-mcp-client/`) is separately
  637. licensed under the **MIT License** so it can be freely embedded in any
  638. agent client without restriction.
  639. **Free production use of the backend** — you may deploy AKB in
  640. production, commercial or not, provided your aggregate deployment
  641. serves **fewer than 100 Named Seats** (distinct human user accounts in
  642. the `users` table, per deployment; service accounts and
  643. 90-day-inactive accounts excluded — see [LICENSE](./LICENSE) for the
  644. precise definition).
  645. **Commercial license required** for any of:
  646. - Production use of the backend at or above 100 Named Seats.
  647. - Offering AKB (modified or not) as a hosted service, on-premises
  648. product, embedded component, or rebranded distribution to third
  649. parties — regardless of seat count.
  650. **Trademarks** — "AKB", "Dnotitia", and "Seahorse" are trademarks of
  651. Dnotitia, Inc. The software license does not grant trademark rights.
  652. Forks and derivative works must be distributed under a different name.
  653. See [TRADEMARKS.md](./TRADEMARKS.md).
  654. For commercial licensing, the rationale behind the BSL transition, or
  655. trademark permission requests, see
  656. [LICENSE-CHANGE.md](./LICENSE-CHANGE.md) or contact
  657. **support@dnotitia.com**.
  658. ## Security
  659. Found a vulnerability? See [SECURITY.md](./SECURITY.md) — please report
  660. privately, not via public issues.
  661. ## Contributing
  662. See [CONTRIBUTING.md](./CONTRIBUTING.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.