Akb

AKB — Agent Knowledge Base

Organizational memory for AI agents. Git-backed 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-mcp stdio proxy
• Custom agents — direct HTTP POST /mcp/ with a Bearer token

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   # Codex

Install 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 in three containers.

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 backing store of Git bare repos and a PostgreSQL hybrid index.

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.

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 emits a structured event 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                           │
│   Git bare repos       │  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 — A Git bare repo. The unit of access control and physical isolation.
• 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, implements in 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_sql runs the user's SQL inside a transaction with SET LOCAL ROLE; cross-vault references return PG 42501 directly. No application-side regex inspects user SQL for forbidden identifiers. See docs/designs/pg-native-rbac/.

MCP Tools (selection)

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.

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}           file

The /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.

---
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
...

Quick Start

AKB ships as a 3-container stack (PostgreSQL with pgvector + backend + frontend). For semantic (dense) search you bring an OpenAI-compatible embedding endpoint (OpenAI, OpenRouter, self-hosted vLLM/TEI, etc.). It is not strictly required: with no embed endpoint (or during an outage) the pgvector and Qdrant drivers degrade to BM25-only lexical search rather than returning nothing — dense is genuinely optional end-to-end (the seahorse-db driver is the exception; see Vector store below). Prefer running a separate Qdrant cluster, or pointing at Seahorse? See Vector store below.

# 1. Configure
cp config/app.yaml.example   config/app.yaml
cp config/secret.yaml.example config/secret.yaml
$EDITOR config/secret.yaml   # set embed_api_key (and jwt_secret for any non-local deploy)

# 2. Run
docker compose up -d

# 3. Open
open http://localhost:3000

config/app.yaml and config/secret.yaml are the single source of runtime configuration — no environment variables are read by the backend. Mount the config/ directory at /etc/akb/ in any deployment.

Vector store (driver-pluggable)

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 pgvector/pgvector image pre-installs the extension; the driver creates a separate vector_index schema, so the main chunks table 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][shc] 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. See [docs/vector-store-seahorse.md](./docs/vector-store-seaho

…