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

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.

MCP protocol compatibility

AKB keeps one tool and authorization core behind two protocol adapters:

The proxy answers either handshake locally and normalizes backend calls to the modern stateless contract when available. Legacy backend sessions are used only during a rolling upgrade when modern discovery is unavailable. 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   # 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 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 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 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                           │
│   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)