dnotitia/akb

> **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-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:
| Surface | Modern | Legacy |
|---|---|---|
| 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 + Mcp-Session-Id lifecycle |
| akb-mcp stdio proxy | 2026-07-28 discovery and per-request metadata | 2025-06-18 initialize |
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.
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
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 |