akb
AKB is an MCP server for a multi-vault, permissioned knowledge base where agents store, search, link, query, and share documents, tables, and files.
Vaults — list/create/archive/delete vaults, inspect info and members, set public access, transfer ownership.
Documents — create, read, update, patch-edit, move/rename, delete Markdown docs with frontmatter (type, status, tags, summary, relations); every write is versioned.
Search — hybrid dense+BM25
akb_searchwith vault/collection/tag/type filters, literal or regexakb_grep(count-only, files-with-matches, find-and-replace), and section-levelakb_drill_down.Navigation —
akb_browsetree traversal over collections, docs, tables, and files with depth control and paging.Tables — create/alter/drop structured PostgreSQL tables with columns, indexes, unique keys; run SELECT/INSERT/UPDATE/DELETE via
akb_sql, including cross-vault joins.Files & images — upload/download/replace/delete binary attachments, and embed validated inline images in documents.
Knowledge graph — inspect relations, link/unlink resources (
depends_on,related_to,implements, etc.), traverse subgraphs, view provenance.History — commit history, activity feeds, diffs, and reading any prior document version.
Permissions — grant/revoke roles (reader/writer/admin) with revocable source-key bases, explain effective access, look up users.
Publishing — create no-auth share URLs for documents, files, or parameterized table queries with password, expiry, and view caps; list, snapshot, or unpublish.
Portability — export/import vaults as Open Knowledge Format bundles.
Guidance —
akb_helpfor tool and workflow documentation.
AKB — Agent Knowledge Base
Organizational memory for AI agents. PostgreSQL-native knowledge base served over the Model Context Protocol (MCP) — agents read and write directly with hybrid semantic + keyword search, structured tables, files, and a URI graph. Drop-in alternative to Confluence / Notion for Claude Code, Cursor, Windsurf, and any MCP-aware agent.
Works with
Any agent client that speaks MCP (Streamable HTTP or stdio):
Claude Code — CLI / VS Code / JetBrains
Claude Desktop — macOS / Windows
Cursor, Windsurf, Cline, Continue — via the
akb-mcpstdio proxyCustom agents — direct HTTP
POST /mcp/with a Bearer token
The default flow uses a Personal Access Token. Deployments with the
optional MCP OAuth Resource Server path turned on (via Keycloak as
the AS — see docs/mcp-clients/web-connectors.md)
also accept Claude Code's mcp add --transport http + mcp login flow
end-to-end, without a PAT.
Related MCP server: Brainstem
MCP protocol compatibility
AKB keeps one tool and authorization core behind two protocol adapters:
Surface | Modern | Legacy |
Direct HTTP |
|
|
|
|
|
The proxy answers either handshake locally and normalizes backend calls to the modern stateless contract when available. For older backends without modern discovery, the proxy can fall back to legacy initialization and retain a session ID if that older server returns one. The current backend runs both adapters statelessly. A process cannot mix generations, and unsupported revisions or conflicting protocol evidence fail closed before a tool or local-file operation runs.
Plugins
Beyond raw MCP access, AKB ships ready-made agent plugins for Claude Code and Codex that wrap common vault workflows:
akb-wiki — ingest a source (local file, web URL, GitHub PR / release / commit, Confluence page, or Jira issue) into the vault as a structured document, and answer questions from the vault with grounded, cited synthesis (read-only).
akb-sessions — capture a coding session as structured notes: a session report plus follow-up tasks, learnings, ideas, and decisions.
akb-claude-code — a Claude Code lifecycle bridge: hooks anchor each session to your AKB memory vault, injecting preferences and recent learnings at the start and writing a recap at the end.
/plugin marketplace add dnotitia/akb # Claude Code
codex plugin marketplace add dnotitia/akb # CodexInstall details and credentials: plugins/.
Try it live
A public demo runs at akb-demo.agent.seahorse.dnotitia.ai.
Browse and search a small fictional-organization knowledge base — product docs,
a company handbook, agent session notes, and an engineering wiki, cross-linked
by the URI graph — right in your browser, no signup. To wire it into your own
agent, sign up with any email (a throwaway address is fine) and point the
akb-mcp proxy at
https://akb-demo.agent.seahorse.dnotitia.ai/mcp/.
⚠️ Throwaway demo. It is public, wiped and re-seeded weekly, and runs on minimal resources with no uptime, privacy, or data guarantees. Don't put anything real or sensitive in it — treat every write as public and ephemeral. For real use, self-host with Docker Compose or Kubernetes.
Why AKB
Most knowledge tools are built for humans clicking through a UI. Agents need a
different shape: structured documents, semantic + keyword search in one call,
explicit relations, and full version history. AKB gives agents a single set of
tools (akb_put, akb_search, akb_browse, akb_relations, …) over a
PostgreSQL-native revision store and hybrid index. Explicit Bare Git installations
remain supported for existing deployments.
Retrieval quality
Memory is only useful if the right note comes back. AKB's hybrid retrieval (dense + BM25, source-level dedup) was benchmarked on LongMemEval-S — 500 long-context questions, ~50 chat sessions per question. Recall@5 = 98.4%, with no reranker in the loop.
System | R@5 | n | Reranker | Source |
AKB hybrid | 98.4% | 500 | no | this repo |
MemPalace hybrid + rerank | 98.4% | 450 | yes | |
gbrain hybrid | 97.6% | 500 | no | |
gbrain vector | 97.4% | 500 | no | gbrain-evals |
Methodology, per-category breakdown, and a one-command reproducible harness
live in eval/longmemeval/. The embedding model differs
across systems (AKB: bge-m3@1024), so read this as a stack-level comparison.
Design philosophy
Core stays small; flexibility comes from extension, not built-in
automation. AKB does not ship its own consolidator, summariser, or
"knowledge gardener" — instead every write records a structured event in the
PostgreSQL outbox. When redis_url is configured, the publisher fans those
events out to a Redis Stream (akb:events). Operators wire any external
consumer (periodic synthesis bot, doc-rot reaper, weekly-digest agent, audit
trail, …) on top, with no patches to the core. The base contract is a
read/write store; opinions about what to do with the knowledge live outside.
Architecture
┌──────────────────────────────────────────────────────────┐
│ Access Layer │
│ MCP Server │ REST API │ Web UI │
├──────────────────────────────────────────────────────────┤
│ Core Services │
│ Document (Put/Get) │ Search (Hybrid: dense+BM25) │
│ Relations (graph) │ Session │ Publications │
├──────────────────────────────────────────────────────────┤
│ Storage Layer │
│ Native revisions │ PostgreSQL 16 (text + meta SoT)│
│ │ Vector store (driver): │
│ │ pgvector (default, PG)│
│ │ qdrant (optional) │
│ │ seahorse-cloud (managed) │
│ │ seahorse-db (self-hosted)│
│ │ seahorse-db-grpc(experimental)│
└──────────────────────────────────────────────────────────┘PostgreSQL is the source of truth — chunk text + metadata + BM25 vocab.
The vector store is a driver-pluggable derived index holding dense
embeddings and corpus-side sparse vectors. Full vector-store loss is
recoverable from PG by setting chunks.vector_indexed_at = NULL and
letting the indexing worker re-populate.
Key Concepts
Vault — The unit of access control and knowledge organization. Native revisions live in PostgreSQL; the legacy backend uses one bare Git repo per vault.
Collection — A directory inside a vault. Topical grouping of documents.
Document — Markdown + YAML frontmatter, optimised for agent read/write.
Hybrid Search — Dense (semantic) + BM25 (lexical) fused via RRF in one call.
Relations —
depends_on,related_to,implementsin frontmatter form an explicit knowledge graph.Vault isolation in
akb_sql— Enforced by PostgreSQL ACL. Each AKB user has a corresponding PG role (akb_user_<uid>) and each vault has three group roles (akb_vault_<vid>_{reader,writer,admin}).akb_sqlruns the user's SQL inside a transaction withSET LOCAL ROLE; cross-vault references return PG42501directly. No application-side regex inspects user SQL for forbidden identifiers. Seedocs/designs/pg-native-rbac/.
MCP Tools (selection)
Tool | Description |
| Vault management |
| Document CRUD (revision + indexing) |
| File attachments — proxy-side (requires local filesystem) |
| Validated inline Markdown images — proxy-side in |
| Tabular content — per-doc tables + SQL |
| Tree traversal (collection → docs) |
| Hybrid search (dense + BM25) / literal grep |
| Section-level retrieval |
| Knowledge graph |
| In-place edit, diff, revision history |
| Permission boundaries — per-user, per-org, public |
| Public publication |
Agent memory and session lifecycle are not MCP tools — they live on
the dedicated /api/v1/agent-sessions REST surface, driven by AKB
lifecycle plugins (akb-claude-code, akb-cursor, …) that hook into
the agent's own SessionStart / PreCompact / SessionEnd events. As an
agent, your own memory vault (agent-memory-{username}) is browsable
through the standard akb_search / akb_browse / akb_get tools
exactly like any other vault.
The full tool catalogue is exposed via akb_help() from any MCP client.
Inline document images from MCP
Inline images are hidden document attachments, not browsable Files. Upload a local PNG, JPEG, GIF, or WebP (maximum 10 MiB), then insert the returned Markdown without reconstructing its asset URL:
image = akb_put_image(
parent="akb://eng/coll/specs",
file_path="/workspace/architecture.png",
alt_text="Request processing architecture")
akb_put(
parent="akb://eng/coll/specs",
title="Request Processing",
content="# Architecture\n\n" + image.markdown)For an existing document, use akb_get followed by a targeted
akb_edit(base_commit=...). Do not pass only the image fragment to
akb_update(content=...), which replaces the complete body. Image bytes are
immutable: replacing an image means uploading a new one and editing the
Markdown reference. Remove an image by deleting its Markdown expression; use
akb_discard_image only for an upload that never reached a successful document
commit. Run akb_help(topic="images") for retention and publication behavior.
The image tools require both the matching backend release and akb-mcp 2.2 or
newer. For upgrades, deploy the backend first, then publish/install the proxy
and restart existing MCP processes so they load the updated tool list.
Document Format
Every vault resource has a location-aware AKB URI — the canonical handle used by every tool and stored in relations. As of 0.3.0:
akb://{vault} vault root (browse target)
akb://{vault}/coll/{coll_path} collection (browse target)
akb://{vault}[/coll/{coll_path}]/doc/{filename} document
akb://{vault}[/coll/{coll_path}]/table/{name} table
akb://{vault}[/coll/{coll_path}]/file/{uuid} fileThe /coll/{coll_path} segment is omitted for resources at the vault
root. Walking up a URI to its parent collection is a pure string
operation — paste the parent into akb_browse(uri=...) to list
siblings without an extra lookup.
For large Vaults, start with akb_browse(uri=..., depth=0, page_size=100)
and follow next_cursor until complete=true, or drill into a Collection.
See bounded navigation and literal-search scope limits
for paging, partial results and protective grep errors.
---
title: "Payment API v2 migration plan"
type: plan # note | report | decision | spec | plan | session | task | reference
status: active # draft | active | archived | superseded
tags: [payments, api]
domain: engineering
summary: "REST → gRPC transition plan."
depends_on: ["akb://eng/coll/specs/doc/payment-api-v2.md"]
related_to: ["akb://eng/coll/meetings/doc/2026-05-01-payments.md"]
---
# Payment API v2 migration plan
...Open Knowledge Format (OKF) compatible
With the explicit Bare Git backend, a vault is stored as a git tree of
.md + YAML-frontmatter files whose
identity is the path — the same model as Google Cloud's
Open Knowledge Format
(OKF v0.1), which AKB independently arrived at before the spec existed.
AKB-authored bundles satisfy all three OKF MUST rules. Server-side
akb_export({"vault": "<vault>", "format": "okf"}) and authenticated
GET /api/v1/vaults/{vault}/export?format=okf support both PostgreSQL Native
and Bare Git through the document service. Bundles contain documents plus
tables/files represented as concept documents.
The offline CLI below reads an existing Bare Git worktree; it does not read
Native storage. Run it from backend/:
cd backend
uv run python -m app.cli okf-export --from-git /data/vaults/_worktrees/<vault> \
--vault <vault> --out ./okf-out/
uv run python -m app.cli okf-validate ./okf-out/OKF and AKB are complementary — OKF standardizes how knowledge is written
down; AKB stores, versions, searches, governs, and serves it to agents. See
okf/ for the mapping and a sample bundle.
Guides
Task-oriented guides for teams evaluating or adopting an agent knowledge layer:
Sharing one agent memory across Claude Code, Cursor, and other MCP clients
Keeping document structure in retrieval: heading-aware chunks and section reads
Self-hosting AKB: license terms, seat counting, and checks before you commit
Applying permissions at query time when agents search shared knowledge
Keeping search current when documents and embedding models change
Quick Start
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 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:3000To 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
application configuration and are mounted read-only at /etc/akb.
AKB_PROCESS_ROLE=all|api|worker only selects process composition;
AKB_TOKENIZER_PROCESSES=1..4 can reduce tokenizer concurrency. Revision
selection is not an environment-variable switch.
See the Native installation guide for image upgrades, bootstrap recovery and Kubernetes. The Compose guide preserves the explicit Bare Git upgrade path. Helm, all-in-one and standalone SSO remain legacy Bare Git compatibility paths in this release. Native does not support document templates or external Git imports; its discovery and API reject those capabilities. Existing migration/history/diff/activity compatibility remains.
Ordinary registration always creates a non-admin account, including on an
empty database. Administrator bootstrap is available only through the
operator CLI; there is no unauthenticated HTTP bootstrap endpoint. The CLI
profile must match auth_mode:
# Local: have AKB generate the password only when an operator-owned output
# file is explicitly requested. A new file is created with mode 0600 and the
# password is not written to stdout, stderr, logs, or application config.
python -m app.cli provision-recovery-admin local \
--username recovery-admin --email recovery-admin@example.com \
--generate-password-file /secure/operator/recovery-admin.password
# SSO: pre-bind the product administrator to the exact external identity.
# Username and email are snapshots; issuer + subject are the identity key.
python -m app.cli provision-recovery-admin sso \
--username recovery-admin --email recovery-admin@example.com \
--issuer https://issuer.example.com/realms/akb \
--subject exact-provider-subjectThe same exact identity is idempotent. A different designation, an existing
username/email, or an already-bound external identity fails closed. The SSO
command stores no usable local password and does not contact the identity
provider. Generated output files are create-only and never overwritten; for a
retry after the file exists, pass that file back with --password-file.
The two local forms differ in one further way. --generate-password-file is
AKB producing a credential and handing it over, so the account it creates owes
a replacement for it: the first session that credential opens can reach the
password change and nothing else, exactly as a password reset behaves.
--password-file installs a value the caller already holds — AKB delivers it
to nobody — so it arms nothing, and an installation that signs in as this
account to bootstrap its own service identity keeps working. To force a
replacement for a credential supplied that way, rotate it afterwards with the
command below; rotation always leaves the account owing a change.
If that credential later leaks, is lost, or has to be taken back, rotate it rather than reprovisioning the account:
# Break-glass: replace the credential and print the new one once. Nothing
# stores or logs the value, and the machine-readable report omits it.
python -m app.cli issue-recovery-admin-credential \
--expected-username recovery-admin \
--expected-email recovery-admin@example.comRotation names the account it expects and refuses any mismatch, so it cannot
act on the wrong one. The credential it replaces stops working immediately,
including one currently in use, and sessions held before the rotation are
revoked — both are what a compromise response requires. The same operation is
available at POST /admin/recovery-admin/issue-credential, which requires an
independent service-administrator token rather than a human session. Rotation
is not available in sso mode: the identity provider holds the credential,
and nothing in a running AKB can replace it.
Open /admin for the separate product-administration surface. In local
mode it accepts the provisioned local administrator and returns the same
local-session-rs256-v2 profile used by local human authentication, but it
refuses non-admin accounts. In sso mode local credentials are absent:
/admin uses a dedicated confidential akb-admin Keycloak client with PKCE
and nonce, then accepts only the exact pre-bound (issuer, subject) whose AKB
account is still active and is_admin=true.
In SSO mode the same /admin surface can configure a built-in upstream IdP,
save it disabled, inspect its exact broker redirect URI, and enable or disable
its ordinary-login option without redeploying AKB. The option becomes a usable
button only when the server-side browser-session capability is ready. Client
secrets are write-only, and an enabled provider must be disabled before
reconfiguration.
See the SSO provider guide, the standards-based
generic OIDC integration, and the stricter
Keycloak OIDC reference. Existing
Kubernetes installations should also follow the
local-to-SSO cutover runbook instead of
treating auth_mode as a rolling one-line configuration change.
The dedicated admin callback stores no Keycloak access, refresh, or ID token.
It creates a short-lived opaque HttpOnly admin cookie plus a CSRF token;
PostgreSQL stores only their hashes plus the exact identity snapshot, and
rechecks the account, unchanged external binding, and admin flag on every
request. Its one-time OIDC state is also bound to a short-lived HttpOnly cookie
so a callback copied into another browser fails before token exchange.
Configure keycloak_admin_client_secret, register
<public_base_url>/api/v1/admin/auth/keycloak/callback and
<public_base_url>/admin in the dedicated client, and keep the admin client ID
out of every API/MCP resource-client path. Browser-facing AKB and Keycloak URLs
must use HTTPS outside the explicit loopback development exception.
Ordinary SSO login uses the separate akb-web client. The browser receives
only an opaque HttpOnly AKB session plus a readable CSRF value; SSO does not
mint an AKB user JWT. AKB encrypts the Keycloak refresh/ID token set with the
independent sso_browser_session_encryption_key and never persists an access
token. The client must map Keycloak's identity_provider user-session note
into both ID and access tokens with oidc-usersessionmodel-note-mapper; AKB
binds that signed broker alias to the selected enabled provider on callback
and every refresh. Production HTTPS cookies use the browser-enforced __Host- prefix,
Secure, no Domain, and Path=/; loopback HTTP uses isolated development
names. Generate the key as 32 random bytes encoded with unpadded base64url and
keep it stable across restarts. See the Keycloak boundary
for refresh, logout, and back-channel revocation details.
Local JWT migration and rotation
Local login issues only the versioned local-session-rs256-v2 profile:
RS256 with an installation-owned RSA-3072 key, an RFC 7638 kid, exact
deployment issuer/audience, jti, and a public-only JWKS at
GET /api/v1/auth/jwks. AKB never chooses a verifier from an untrusted token
alg header. Upgrading from an HS256 release is an intentional forced-login
boundary: generate and persist the v2 keyset before rollout, set
jwt_algorithm: RS256, and restart all backends together. Existing HS256 user
sessions then receive 401 and must sign in again; PATs and service keys are not
revoked. Internal HMAC capabilities use system_hmac_secret. An old
jwt_secret key now fails startup. If system_hmac_secret is already set,
delete jwt_secret and keep system_hmac_secret as it is; otherwise rename
jwt_secret to system_hmac_secret with the value unchanged. Either way the
secret in effect stays the same, so links and cursors signed with it keep
working.
For routine v2 key rotation, generate a new directory while retaining the current public JWKS, publish the new immutable Secret/config revision, and roll every backend to that exact pair:
cd backend
uv run python -m app.cli generate-local-session-keyset \
--output-dir /secure/akb/local-session-next \
--retain-jwks /secure/akb/local-session-current/jwks.jsonKeep a retained public key for at least jwt_expire_hours plus rollout skew,
then remove it in a later coordinated keyset revision. Restoring the previous
private/JWKS pair is the rollback; never overwrite key files in place.
Vector store (driver-pluggable)
See BM25 statistics and VChord-only deployments for weight conventions, external statistics consumers and posting rollback requirements.
Hybrid search (dense + BM25 sparse, RRF-fused) runs through a driver interface. Five drivers ship; pick at config time:
pgvector(default) — uses the same Postgres container that holds application data. The install paths build that container's image fromdeploy/postgres/Dockerfile: pgvector plus thevchord_bm25BM25 index, which gives a new database the defaultvchordsparse shape. The driver creates a separatevector_indexschema, so the mainchunkstable stays plain PostgreSQL. RRF fusion runs application-side. No external service to operate.qdrant— runs a separate Qdrant container; native RRF via the Query API. Useful when you already operate Qdrant or want to scale the vector store independently of Postgres.seahorse-cloud— points at a managed Seahorse Cloud table over its BFF management API + per-table data-plane host (Bearer auth). No infrastructure to run on your side; you provision a table in the Seahorse console (or let the driver auto-create one) and AKB stores its chunks there. Native RRF, server-side BM25. Seedocs/vector-store-seahorse.mdfor the end-to-end setup walkthrough (sign-up → token → schema → config).seahorse-db— points at a self-hosted SeahorseDB cluster via its Coral coordinator HTTP API. You run Coral + Writer + Reader(s) + Redis + Kafka + a sparse-embedding server yourself (the SeahorseDB monorepo'sdeploy/docker-compose.ymlbrings up a minimal single-box stack). Native dense+sparse hybrid. Unlike the other drivers it does not support BM25-only fallback when the embed API is down (its sparse path is server-side and structurally coupled to a live embed step) — keep an embedding endpoint reachable for this driver.seahorse-db-grpc(experimental) — same Coral coordinator asseahorse-db, sameseahorsedb_*settings, but talks gRPC instead of REST/JSONL. Coral merges axum + tonic onto a single listener so the port doesn't change; only the wire format does. Trades the JSON parsing path (and a class of foot-guns like INT64 sign mismatch and Arrow JSON decoder edge cases) for typed protobuf messages and an Arrow IPC streaming result. Prefer the REST driver for production until the gRPC variant clears its own QPS / recall benchmark. Same CRUD parity with REST (passes the same 25-scenario hybrid e2e), but it has not yet had the production-scale exposure the REST driver has.
Switching drivers is a config edit (no schema migration on the main DB):
# Default flow targets pgvector.
docker compose up
# Qdrant:
docker compose -f docker-compose.yaml -f docker-compose.qdrant.yaml up
$EDITOR config/app.yaml # vector_store_driver: qdrant
# vector_url: http://qdrant:6333
# Seahorse Cloud (managed; full guide in docs/vector-store-seahorse.md):
docker compose up # no extra container needed
$EDITOR config/app.yaml # vector_store_driver: seahorse-cloud
# seahorse_cloud_tenant_uuid: <your tenant>
# seahorse_cloud_table_name: <your table>
$EDITOR config/secret.yaml # seahorse_cloud_token: shsk_<...>
# SeahorseDB (self-hosted cluster reached via the Coral coordinator):
docker compose up # run the SeahorseDB stack separately
$EDITOR config/app.yaml # vector_store_driver: seahorse-db
# seahorsedb_coordinator_url: http://localhost:3003
# seahorsedb_table_name: akb_chunksEmbedding model + dimensions are also fully pluggable via
embed_base_url / embed_model / embed_dimensions — the codebase has
no hard-coded model. For pgvector with HNSW, keep embed_dimensions ≤ 2000
(or 4000 with halfvec); larger models fall back to exact scan.
Qdrant / Seahorse (cloud or db) have no such limit (Qdrant up to 65536,
Seahorse up to its table-defined dim).
LLM features (optional)
LLM is only used by the metadata_worker to auto-tag documents imported via
external git mirroring. Core CRUD/search works without it. To enable, set
llm_base_url / llm_model in app.yaml and llm_api_key in secret.yaml.
Standalone deployments default to model_api_governance_mode: external_metering
and may point embedding, chat, and rerank at any compatible provider. A managed
control plane can instead set platform_hard plus an exact
platform_gateway_base_url. In that mode AKB fails startup if an active model
route points anywhere else or lacks a credential, and every model call carries
a caller-generated Idempotency-Key for durable gateway reservation/settlement.
Gateway policy or budget denials are never fanned out into per-item retries.
Event fanout (optional)
The PG events outbox is always written. Set redis_url in app.yaml to
have the events_publisher worker drain the outbox to a Redis Stream
(akb:events) so external services can subscribe via XREAD / consumer
groups. Leave blank to disable Redis fanout; the authenticated
GET /api/v1/events/{vault} SSE tail reads the same PG outbox. Native document
writes participate in this outbox at the authority transaction boundary.
See the change-event contract for supported
File/document actions, move identity, retry semantics and consumer recovery.
Audit log (optional)
Off by default. Set audit.enabled: true in app.yaml to emit a structured,
append-only, hash-chained JSON-lines audit log at the MCP dispatch
chokepoint — every read, write, and auth denial, uniformly. AKB is a
producer only: it does not store, query, or retain audit data; your SIEM
(Splunk/QRadar/Elastic) scrapes the stream and owns retention under its own
compliance regime. Each line carries a monotonic seq plus
sha256(prev ‖ line), so the chain can be verified for dropped or altered
lines and re-seeds from disk across restarts. Optionally hand the daily
rolled file off to a WORM object-storage bucket (audit.bucket —
provision with Object Lock and a write-only key for a true immutable trail);
the local buffer is pruned only after a confirmed upload. Capture is
best-effort and never raises into the serving path. See
config/app.yaml.example for the full audit: block.
Production deployment
For Kubernetes, start with the
deployment guide. AKB provides standalone local and
standalone-SSO resource sets through both Helm and Kustomize.
Use the dependency-free
AKB Helm chartfor a standardhelm upgrade --installworkflow.Use
deploy/k8sfor the standalone Kustomization ordeploy/k8s/standalone-ssofor an installation-owned Keycloak stack.Both paths consume pre-existing, operator-owned Kubernetes Secrets. AKB does not install or operate a credential service or synchronization controller.
Real hostnames, registries, storage classes, TLS issuers, and provider settings belong in Helm values or an operator-owned Kustomize overlay; do not commit production credentials to this repository.
Project Structure
akb/
├── backend/ # Python 3.14 / FastAPI / asyncpg / GitPython
│ ├── app/
│ │ ├── api/routes/ # REST endpoints
│ │ ├── services/ # Business logic + workers
│ │ └── db/ # PostgreSQL schema + migrations
│ ├── mcp_server/ # Streamable HTTP MCP server
│ └── tests/ # E2E shell tests
├── frontend/ # React 19 + TypeScript + Vite + Tailwind
├── packages/
│ ├── akb-client/ # REST SDK boundary (npm: @akb/client)
│ └── akb-mcp-client/ # stdio ↔ HTTP MCP proxy (npm: akb-mcp)
├── agents/ # Reference Python agent runtime (think/act loop over MCP)
├── plugins/ # Claude Code / Codex agent plugins (ingest, query, session capture, lifecycle)
├── templates/ # Doc templates (ADR, PRD, runbook, …) and vault profiles
├── okf/ # Open Knowledge Format interop: positioning + sample bundle
├── design-system/ # Frontend design system docs
├── config/
│ ├── app.yaml.example # Non-secret runtime settings
│ └── secret.yaml.example # API keys, passwords (gitignored when not .example)
├── deploy/
│ ├── all-in-one/ # Single-container demo image
│ ├── helm/
│ │ └── akb/ # AKB chart with local and standalone-SSO profiles
│ └── k8s/
│ ├── *.yaml # Standalone AKB + PostgreSQL resources
│ └── standalone-sso/ # Standalone plus owned Keycloak and its database
└── docker-compose.yaml # Local stack (PG + MinIO + API + worker + frontend)Tech Stack
Backend: Python 3.14, FastAPI, Uvicorn, asyncpg, GitPython, MCP SDK
Database: PostgreSQL 16 (main DB needs no extension; the same pgvector/pgvector image hosts the optional vector_index schema)
Vector store: driver-pluggable (pgvector default; Qdrant, Seahorse Cloud, or self-hosted SeahorseDB optional — hybrid dense + BM25 sparse, RRF fusion; BM25-only fallback when embed is down)
Event stream (optional): PG
eventsoutbox + Redis Streams fanoutAudit log (optional): hash-chained append-only JSONL at the MCP dispatch point + optional WORM S3 handoff; producer-only (SIEM owns retention)
Frontend: React 19, TypeScript, Vite, Tailwind CSS v4, Radix UI
Auth: local RS256 sessions or Keycloak SSO, plus Personal Access Tokens (PATs) for API and MCP access
MCP: Streamable HTTP (backend) + stdio proxy (
akb-mcpon npm)
Versioning
AKB follows SemVer. The backend product version lives in
backend/pyproject.toml ([project].version). A coordinated release uses
scripts/bump-version.sh <x.y.z> to update it together with
frontend/package.json. With image building enabled, each
deploy/k8s/deploy.sh run tags the Docker images with both the
explicit backend version (:${VERSION}) and :latest, so historical builds
remain pullable for rollback.
packages/akb-mcp-client (the akb-mcp npm proxy) follows its own npm
semver lifecycle and is not tied to the product version.
License
The AKB backend, frontend, and deployment manifests are licensed under the Business Source License 1.1 — source-available, with an Additional Use Grant that permits production use (commercial or non-commercial) up to a seat-count threshold, automatically converting to Apache License 2.0 four years after each version's first public release.
The npm akb-mcp proxy (packages/akb-mcp-client/) is separately
licensed under the MIT License so it can be freely embedded in any
agent client without restriction.
Free production use of the backend — you may deploy AKB in
production, commercial or not, provided your aggregate deployment
serves fewer than 100 Named Seats (distinct human user accounts in
the users table, per deployment; service accounts and
90-day-inactive accounts excluded — see LICENSE for the
precise definition).
Commercial license required for any of:
Production use of the backend at or above 100 Named Seats.
Offering AKB (modified or not) as a hosted service, on-premises product, embedded component, or rebranded distribution to third parties — regardless of seat count.
Trademarks — "AKB", "Dnotitia", and "Seahorse" are trademarks of Dnotitia, Inc. The software license does not grant trademark rights. Forks and derivative works must be distributed under a different name. See TRADEMARKS.md.
For commercial licensing, the rationale behind the BSL transition, or trademark permission requests, see LICENSE-CHANGE.md or contact support@dnotitia.com.
Security
Found a vulnerability? See SECURITY.md — please report privately, not via public issues.
Contributing
See CONTRIBUTING.md.
Available Tools
50 toolsakb_activityA
Get activity history for a vault — who changed what, when, and why. Returns Git commit history with changed file list. Use akb_diff to see the actual content changes for a specific commit.
Inputs: vault (required), limit, since, author, +1 more.
akb_alter_tableC
Modify a table's schema — add, remove, or rename columns via ALTER TABLE DDL. Requires admin role.
Inputs: uri (required), add_columns, add_indexes, drop_columns, +6 more.
akb_archive_vaultA
Archive a vault (makes it read-only). Only the owner can do this.
Inputs: vault (required), _vault_skill_ack.
akb_browseA
Browse ALL vault content — documents, tables, and files — under a browse root. The browse root can be addressed two ways: pass a canonical uri (akb://V for vault root or akb://V/coll/X for a collection), or the legacy vault + optional collection pair. Use the URI form when drilling down from a previous response — every item carries a uri that can be pasted straight back in.
depth is tree-depth from the browse root, mirroring tree -L N: 0 = direct children only (no descent), N = descend N collection levels, -1 = entire subtree. Collection rows are always emitted as navigation aids regardless of depth.
The response includes metadata for the current browse root in context, and collection items include summary by default so agents understand their intended purpose. Other resource summaries stay opt-in so large vaults fit in the agent's context window. Returns {vault, path, context, items, total, returned, truncated?, hint?}.
Inputs: uri, depth, limit, vault, +7 more.
akb_create_collectionA
Create an empty collection (folder) inside a vault. Idempotent — returns {created: false} if the collection already exists. Writer or higher role.
Inputs: path (required), vault (required), summary, _vault_skill_ack.
akb_create_tableA
Create a structured data table in a vault. The response carries the canonical uri — akb://{vault}/coll/{collection}/table/{name} when stored under a collection, or akb://{vault}/table/{name} at the vault root. Tables live alongside documents inside collections and follow the same permissions. Define columns with name and type (text, number, boolean, date, json). Optional collection (e.g. 'sessions/learnings') groups the table under that collection so it appears beside the documents and files there in akb_browse; omit for vault root.
Inputs: name (required), columns (required), vault, parent, +6 more.
akb_create_vaultA
Create a new knowledge base vault (a separate, access-controlled repository for documents). Pass external_git to instead create a read-only mirror of an upstream git repo — the vault tracks the remote on a polling schedule and rejects user writes.
Inputs: name (required), template, description, external_git, +2 more.
akb_deleteB
Delete a document. Removes from Git, search index, and knowledge graph.
Inputs: uri (required), _vault_skill_ack.
akb_delete_collectionA
Delete a collection. If empty, removes the metadata row. If non-empty, requires recursive=true to cascade delete every document, file, and table under the path. Cascade emits one git commit for the document batch. Writer or higher role; admin or higher when any table is included.
Inputs: path (required), vault (required), recursive, _vault_skill_ack.
akb_delete_fileC
Delete a file from vault storage by its URI.
Inputs: uri (required), _vault_skill_ack.
akb_delete_vaultA
Permanently delete a vault and ALL its data — documents, chunks, tables, files, edges, Git repo. This cannot be undone. Owner or admin only.
Inputs: vault (required), _vault_skill_ack.
akb_diffA
Get the content diff for a document at a specific commit. Shows what was added/removed/modified. Use akb_history or akb_activity to find commit hashes first.
Inputs: uri (required), commit (required).
akb_discard_imageA
Discard a document image upload that was never committed in an AKB document. Use this only to clean up after a failed or abandoned akb_put/akb_update. Images already claimed by a document or retained Git revision cannot be discarded through this tool.
Inputs: url (required), vault, parent, _vault_skill_ack.
akb_drill_downA
Read section-level (L3) content of a document, or list its section headings. Two modes:
mode='sections'(default): return body content of matched sections. Filter withsection(heading substring) and/orpattern(substring grep on body). On empty match the response carries anoutlineso you can retry.mode='outline': return heading paths only (no bodies). Use this to discover the document's structure cheaply before deciding which section to read. Returns {uri, sections|outline, returned, total?, truncated?, hint?}.
Inputs: uri (required), mode, pattern, section.
akb_drop_tableA
Permanently delete a table and all its rows. Cannot be undone. Requires admin role on the vault.
Inputs: uri (required), _vault_skill_ack.
akb_editA
Edit a single document by replacing exact text. Scope is one document. old_string must be unique within the document (or use replace_all). If old_string is not found or appears multiple times, the call fails with a clear error. Use this for inserting, replacing, or removing an inline image without resending the complete document body. For find-and-replace across many documents, use akb_grep with replace instead.
Inputs: uri (required), new_string (required), old_string (required), message, +3 more.
akb_explain_accessA
Explain why a user holds the role they hold on a vault: every independent basis, and the effective role derived from them. A member list shows the result, never the reasons.
Inputs: user (required), vault (required).
akb_exportA
Export an entire vault as a portable knowledge bundle. Returns the bundle inline as a {path: content} map. The format parameter selects the on-disk format — currently 'okf' (Open Knowledge Format: markdown + YAML frontmatter, the only required field being type). Documents export 1:1; tables and files become OKF concept documents (schema / metadata + a resource pointer — the rows/bytes stay in AKB). Reader role required. For a downloadable zip, use the REST endpoint GET /api/v1/vaults/{vault}/export.
Inputs: vault (required), format.
akb_getA
Retrieve a document by its URI. Returns full content with metadata. Use akb_browse or akb_search first to obtain the URI. Optionally pass a commit hash (from akb_history) to read a previous version.
Inputs: uri (required), version.
akb_get_fileA
Download a file from vault storage to a local path. Pass the file URI — akb://{vault}[/coll/{coll_path}]/file/{uuid} — from akb_browse or akb_put_file.
Inputs: uri (required), save_to (required).
akb_grantA
Grant vault access to a user. You must be owner or admin of the vault. A rule-driven grantor should name its own source_key so it can later withdraw its own reason without deleting anybody else's.
Inputs: role (required), user (required), vault (required), revision, +2 more.
akb_graphA
Get a same-vault knowledge graph — nodes (documents, tables, files) and edges (relations). Provide uri to get a subgraph centered on any resource with BFS traversal. Provide vault (without uri) to get the full vault graph.
Inputs: uri, hops, limit, vault.
akb_grepA
Search for exact text or regex patterns across document content. On a native Document backend, optionally include admitted searchable text Files with measurement_include_text_files=true; binary Files remain excluded. Unlike akb_search (semantic/meaning-based), this finds exact string matches — use it for specific terms, URLs, code snippets, version numbers, etc. Returns matching documents (each with its uri) and matched lines. Optionally pass replace to find-and-replace across all matching documents; the call writes nothing if the scope exceeds max_replacements. Three response shapes (mutually exclusive): default lines, count_only=true (grep -c — per-doc counts + total, no snippets), files_with_matches=true (grep -l — just the URIs that contain the pattern). The default shape always reports BOTH returned_* (what fit under limit) and total_* (full corpus matches) plus a truncated flag. When response safety bounds truncate snippets, the truncation object names the applied resource, match, and byte limits; use count_only for exact counts without snippets.
Inputs: pattern (required), limit, regex, vault, +8 more.
akb_helpA
Get help on AKB tools and workflows. Call with no arguments for an overview. Drill down into categories or specific tools for details and examples. START HERE if you're new to AKB.
Inputs: topic, vault.
akb_historyA
Get version history of a document — who changed it, when, and why. Each entry is a Git commit. Use the commit hash with akb_get to read a previous version.
Inputs: uri (required), limit.
akb_importA
Import a knowledge bundle into a vault. Pass files as a {path: content} map (the shape akb_export returns). format selects the bundle format — currently 'okf'. Concept documents are imported as AKB documents; a type: table/file concept doc (which carries only schema/metadata, not rows/bytes) imports as a regular document describing that asset. Existing paths are skipped, not overwritten. Records targeting the reserved 'overview' collection or carrying type='skill' are skipped per-record and reported in the response's 'reserved' list. Writer role required.
Inputs: files (required), vault (required), format, status, +1 more.
akb_linkA
Create a relation between any two resources (documents, tables, files). Source and target are AKB URIs in the same vault. Relation types: depends_on, related_to, implements, references, attached_to, derived_from. Example: link a design doc to its data table, or attach a diagram file to a spec.
Inputs: source (required), target (required), relation (required), _vault_skill_ack.
akb_list_vaultsA
List accessible vaults as {name, description} pairs. Response is slim — no metadata (id/role/created_at) — to fit large tenants in agent context. Returns {vaults, total, returned, truncated?, hint?}. Optional args:
filter: substring match on name+description (case-insensitive). Use to narrow to a domain (e.g. filter='finance').
limit / offset: pagination when there are many matches.
include_archived: include archived vaults (default false).
Inputs: limit, filter, offset, include_archived.
akb_moveA
Move or rename a document — change its collection and/or slug while keeping its identity and full git history. The old akb:// URI keeps resolving (a redirect is recorded), and graph links/publications are rewritten. Provide collection and/or slug (at least one must change). The title is unchanged; use akb_update to change the displayed title.
Inputs: uri (required), slug, message, collection, +1 more.
akb_provenanceA
Get provenance for a document — who created it, when, which entities were extracted, and its visible same-vault relations.
Inputs: uri (required).
akb_publicationsA
List every publication in a vault. Each item is the canonical publication dict (same shape as akb_publish returns).
Inputs: vault (required), resource_type.
akb_publication_snapshotA
Freeze a table_query publication's current result to S3 and flip its mode to 'snapshot' (subsequent visits return the cached result). Identified by slug alone — the vault is resolved from the publication. Returns the updated publication dict.
Inputs: slug (required), _vault_skill_ack.
akb_publishA
Create a public, no-auth share URL for a document, file, or table query. Document/file: pass the resource uri. Table query: pass query_sql plus vault (and query_vault_names if the query touches more than one). Returns the canonical publication dict — slug is the only identifier you need; share_url is always an absolute URL ready to paste.
Inputs: uri, title, vault, password, +9 more.
akb_putB
Store a new document. The response carries the canonical uri — akb://{vault}/coll/{collection}/doc/{filename} when stored under a collection, or akb://{vault}/doc/{filename} at the vault root. Use that URI to address the document from every other tool. Automatically chunked and indexed for semantic search.
Inputs: title (required), content (required), file, slug, +11 more.
akb_put_fileA
Upload a local file to a vault's file storage (S3-backed). Use for PDFs, images, datasets, or any binary content too large for akb_put. Response includes the canonical uri — akb://{vault}/coll/{collection}/file/{uuid} when stored under a collection, or akb://{vault}/file/{uuid} at the vault root — pass that to akb_get_file / akb_update_file / akb_delete_file. MIME type is auto-detected from the filename extension unless overridden.
Inputs: file_path (required), vault, parent, mime_type, +3 more.
akb_put_imageA
Upload a local PNG, JPEG, GIF, or WebP (maximum 10 MiB) for inline use in an AKB Markdown document. Returns a stable /api/assets/{uuid} URL and a ready-to-paste markdown image expression. For a new document, place it with akb_put. For an existing document, prefer a targeted akb_edit; akb_update(content=...) replaces the entire body and must never receive only an image fragment. Images are immutable: upload a replacement and edit the Markdown reference. This creates a hidden document attachment, not a standalone File; use akb_put_file when the binary should appear in browse/search. If the document write fails, call akb_discard_image with the returned URL.
Inputs: file_path (required), vault, parent, alt_text, +2 more.
akb_relationsA
Get relations for any resource (document, table, or file). Shows same-vault cross-type connections: doc→table, doc→file, table→file, etc. Each row identifies whether it is an explicit link or implicit document-derived edge.
Inputs: uri (required), type, direction.
akb_revokeA
Revoke a user's vault access. You must be owner or admin. Omit source_key and the person is out of the vault entirely; name one and only that basis is withdrawn, which may downgrade rather than remove.
Inputs: user (required), vault (required), revision, source_key, +1 more.
akb_searchA
Search documents with hybrid retrieval — dense vector (semantic) fused with BM25 sparse (keyword) via Reciprocal Rank Fusion. Handles both natural-language questions and short keyword queries well. For exact string / regex matches (code, URLs, version numbers) prefer akb_grep. Returns each hit's uri; collection_summary and vault_description describe the hit's parent context but do not affect matching or ranking. Use akb_drill_down or akb_get with that URI for full content. Response reports returned (in results) and total_matches (size of the deduped prefetch pool — NOT a corpus-wide hit count; vector ANN is top-K only). When truncated=true the prefetch pool was capped, meaning the corpus may hold more hits than reported — switch to akb_grep with count_only=true for an exact literal-substring count, or refine the query. When degraded=true the retrieval index hit a transient failure (vector-store outage or a degraded leg), so results may be incomplete or empty — this is NOT a genuine zero-match; degradation_reason names the cause. Retry shortly, or fall back to akb_grep for a literal search.
Inputs: query (required), tags, type, limit, +4 more.
akb_search_usersA
Search for users by username, display name, or email. Use this to find users before granting vault access.
Inputs: limit, query.
akb_set_publicA
Set vault public access level. Owner only. 'none'=private, 'reader'=public read, 'writer'=public read+write.
Inputs: level (required), vault (required), _vault_skill_ack.
akb_sqlA
Execute SQL on vault tables. Tables are real PostgreSQL tables. Use table names directly (e.g. 'pipeline', 'partners') — they are auto-resolved to the vault's tables. For cross-vault queries, list all vaults in the vaults parameter. Prefix table names with vault name for cross-vault: sales__pipeline, external_projects__partners. SELECT requires reader role. INSERT/UPDATE/DELETE requires writer role. Add a LIMIT to SELECTs unless you truly need every row — the full result set is returned (nothing is silently truncated), so an unbounded SELECT on a large table can send back a very large response.
Inputs: sql (required), vault, vaults, _vault_skill_ack.
akb_transfer_ownershipA
Transfer vault ownership to another user. The current owner or a system admin can do this.
Inputs: vault (required), new_owner (required), _vault_skill_ack.
akb_unlinkA
Remove an explicit same-vault relation between two resources. Implicit relations are removed by editing their source document. If relation type is omitted, removes all explicit relations between the two resources.
Inputs: source (required), target (required), relation, _vault_skill_ack.
akb_unpublishA
Remove publication(s). Pass slug to remove one specific publication, OR uri to remove every publication of that document/file resource (handy when re-publishing). table_query publications have no resource URI, so remove them by slug. Returns {deleted: N}.
Inputs: uri, slug, _vault_skill_ack.
akb_updateA
Update an existing document. Only provide fields you want to change. The content field replaces the complete Markdown body; never pass a partial fragment such as a newly uploaded image. Use a targeted akb_edit for inline insertion or replacement.
Inputs: uri (required), file, tags, type, +11 more.
akb_update_fileA
Replace the bytes of an existing vault file while preserving its URI. The local file is hashed before transfer; identical content is skipped. Pass expected_content_hash and/or expected_version from akb_get_file to reject stale writes with HTTP 409 instead of overwriting a concurrent change.
Inputs: uri (required), file_path (required), mime_type, _vault_skill_ack, +2 more.
akb_vault_infoA
Get detailed vault information: owner, member count, document/table/file/edge counts, last activity.
Inputs: vault (required).
akb_vault_membersA
List all members of a vault with their roles (owner, admin, writer, reader).
Inputs: vault (required).
akb_whoamiA
Get your current profile — username, email, display name, role. Use this to check who you are authenticated as.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 50 tools
The resource-specific variants (put/put_file/put_image, get/get_file, delete/delete_file/delete_collection/delete_vault, update/update_file/edit) have overlapping verbs and could be misselected without close reading, but the descriptions carefully distinguish semantic search from grep, document content from file bytes, and vault-scoped activity from per-document history. Overall, an agent can disambiguate with effort, but the boundaries are not immediately obvious from names alone.
All 50 tools use a consistent akb_ + snake_case verb_noun pattern (list_vaults, create_table, delete_file) with only a few bare verbs (put, get, update, delete, sql, grep) that still fit the naming system. There is no mixing of conventions or unpredictable style.
At 50 tools this is a very large surface even for a comprehensive knowledge-base server; the count dimension explicitly treats 25+ as too many. The breadth of domains (vaults, docs, tables, files, graph, publications, access) explains some of the size, but the surface could be consolidated (e.g. file/image variants, publication helpers).
The server covers the full lifecycle for vaults, documents, tables, files, collections, access control, publications, and import/export, plus search, graph, history, and help. Minor gaps exist—no vault metadata/rename tool, no collection rename, and table row management is only via raw SQL—but they are workable.
Maintenance
Related MCP Connectors
Agent-native notes, tasks, dev-docs, vaults, sync & handoffs. MCP + OpenAPI dual surface.
Cloud or self-hosted knowledge for AI agents: hybrid search, reranking, GraphRAG, scoped MCP tools.
A second brain for your AI agent. Shared memory for your team's AI agents, plus public and private knowledge bases — works with ChatGPT, Claude, Cursor and any MCP client.
Shared product-knowledge graph for AI agent fleets — vault tools + agent self-signup over MCP.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceLocal-first, file-based memory layer for AI agents — one shared Markdown vault across Claude, Codex, Gemini, Cursor and any MCP client. Provides read/write memory tools with an audit trail, per-agent trust levels, and Git sync; no cloud and no lock-in.2MIT
- AlicenseNot gradedqualityDmaintenanceLocal-first knowledge backend for AI agents that connects MCP hosts to an Obsidian-compatible vault with indexed retrieval, token-budgeted memory recall, and secure ingestion.1MIT
- AlicenseNot gradedqualityCmaintenanceGoverned knowledge base for AI agents via the Model Context Protocol (MCP), enabling agents to search, read, and contribute persisted knowledge with versioning, audit trails, and approval workflows.78 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to persist, search, and evolve knowledge through a Markdown vault with a typed knowledge graph and MCP interface.15Apache 2.0