What dnotitia/akb does
dnotitia/akb provides a knowledge base for AI agents, organized into access-controlled vaults. Content can include Markdown documents with YAML frontmatter, structured tables, and attached files. Documents, collections, and other resources can be connected through a URI-based knowledge graph, allowing agents to follow explicit relationships such as dependencies, related items, and implementations.
PostgreSQL is the primary source of truth for document text, metadata, revisions, and lexical-search data. Native revision history supports reviewing changes over time, while the system can also publish selected content through public links. Vaults provide the main boundary for organizing knowledge and controlling access across users and organizations.
How it works
Agents communicate with the tool layer using MCP. The server can be reached directly through a stateless HTTP MCP endpoint or through the akb-mcp stdio proxy. The proxy supports local-file operations, including file attachments and validated inline Markdown images in version 2.2 and later.
Search combines dense semantic retrieval with BM25 keyword matching and fuses the results in a single request. Literal grep is available when exact text matching is more appropriate. A separate drill-down operation retrieves content at section level, while browse traverses the hierarchy from collections to documents.
Dense embeddings and sparse corpus vectors are kept in a replaceable vector-store driver, while PostgreSQL retains the authoritative content and metadata. Supported storage arrangements include pgvector by default, with optional Qdrant and Seahorse-based drivers. Index data can be rebuilt from PostgreSQL if the vector store is lost.
Setup and configuration
The npm package akb-mcp provides the stdio proxy. The default authentication flow uses a Personal Access Token. Custom agents can send authenticated HTTP requests to /mcp/ with a Bearer token. Deployments that enable the MCP OAuth Resource Server path can also use Keycloak for authorization and support Claude Code's HTTP transport and login flow.
Claude Code and Codex plugins are distributed with the repository. The plugin marketplace commands are:
/plugin marketplace add dnotitia/akb for Claude Codecodex plugin marketplace add dnotitia/akb for Codex
The repository also describes Docker Compose and Kubernetes as deployment options for self-hosting.
Tools and capabilities
akb_list_vaults manages vault access and discovery.akb_put creates or updates documents while recording revisions and indexing content.akb_put_file attaches files through the proxy and requires access to a local filesystem.akb_put_image validates inline Markdown images through akb-mcp 2.2 or later.akb_create_table adds tabular content that can be queried per document and with SQL.akb_browse walks collections and their documents.akb_search performs hybrid semantic and BM25 retrieval or literal grep.akb_drill_down retrieves individual document sections.akb_relations reads and works with the URI knowledge graph.akb_edit supports in-place changes, diffs, and revision history.akb_grant sets per-user, per-organization, or public permission boundaries.akb_publish publishes content for public access.
The repository also includes akb-wiki, akb-sessions, and akb-claude-code plugins for ingestion and grounded answers, session capture, and Claude Code lifecycle memory workflows.
Limitations and notes
The public demonstration is periodically wiped and re-seeded, runs on minimal resources, and should not be used for sensitive or durable data. AKB's core records write events in a PostgreSQL outbox; optional Redis configuration publishes them to the akb:events stream for external consumers. Consolidation, summarization, and similar automation are intended to be implemented by those external consumers rather than built into the core server.