# kumbuka
**Shared, persistent memory for AI assistants working with a team โ
served over MCP, curated through an admin console, with a private space that stays private.**
[](https://github.com/kumbuka-ai/kumbuka/actions/workflows/ci.yml)
> **Status: pre-beta.** kumbuka is in active development. The architecture and
> data model are settled and the private-memory guarantee is a hard design
> constraint, but the project is not yet a hardened, shipped product. Expect
> rough edges and breaking changes.
*kumbuka* is Swahili โ the imperative **"remember!"**. The project lives at
[kumbuka.ai](https://kumbuka.ai).
---
## The problem: the context tax
AI assistants are stateless between sessions. A team using them pays the same
toll over and over โ re-explaining the things that should simply be known:
- *"We use Postgres as the system of record."*
- *"Money is integer minor units, never floats."*
- *"Service names are kebab-case."*
That steering knowledge โ the decisions, conventions, and constraints that
shape how an assistant should work โ is exactly what an assistant ought to
*remember* and apply without being told again. Today it lives in people's heads
and in scattered chat history, so every new session starts from zero.
## What kumbuka is
kumbuka makes that knowledge a first-class, team-owned asset. It gives a team a
durable, shared place for the rules an assistant should carry across
conversations, and serves them to any MCP-capable assistant (Claude and others)
over a remote **MCP server**. A web **admin console** lets the team curate the
shared memory.
It is deliberately **not** a document store or a RAG index. kumbuka holds
*work-steering knowledge* โ a small, typed set of decisions, conventions,
constraints, definitions, open questions, and status โ not a copy of your docs
or source, which stay in their own systems.
- **Shared and curatable** โ the team sees and edits what the assistant relies
on, instead of each person accumulating an opaque, divergent context.
- **Portable** โ any MCP-capable assistant reads and writes it through one
endpoint.
- **Bounded** โ a fixed taxonomy and explicit scopes keep the memory legible
rather than letting it sprawl.
## The private-memory guarantee
> **A member's private memory is theirs alone.** It is reachable only by them,
> only over their own authenticated MCP session. **No admin, no console screen,
> and no team-facing API can read it.**
This is the backbone of the product, not a feature flag. It is enforced at the
**data-access layer** โ the privileged (admin/console) code paths have no route
that can return private rows โ **not** by a configuration toggle that could be
flipped. Disabling a member suspends their account but leaves their private
memory untouched and theirs.
See [the Security & privacy guide](https://docs.kumbuka.ai/operations/security/) for how this is structurally enforced.
## Quickstart (self-host the Community Edition)
The Community Edition is the free, self-hosted, single-tenant memory core. It
runs as a single Docker Compose stack (backend ยท PostgreSQL ยท Keycloak ยท Caddy).
The deployable stack lives in the
[`kumbuka-server`](https://github.com/kumbuka-ai/kumbuka-server) repository:
```bash
git clone https://github.com/kumbuka-ai/kumbuka-server
cd kumbuka-server
cp .env.example .env # set your domain + secrets
docker compose --profile app up -d # backend + postgres + keycloak + caddy
```
The admin console is a separate service, added to the same stack via a small
`compose.override.yml` โ see the step-by-step
**[Quickstart guide](https://docs.kumbuka.ai/get-started/quickstart/)**, which also covers prerequisites,
first run, and the [`kumbuka-server` runbook](https://github.com/kumbuka-ai/kumbuka-server#quick-start-dev)
for production deployment.
## Connect your assistant
kumbuka is reached by AI clients as a **custom MCP connector** โ the endpoint
URL is all a client needs; there is no client id and no client secret. In
claude.ai you add it under **Settings โ Connectors**, sign in once through the
OAuth flow, and your assistant can then call the memory tools on your behalf,
including your own private scope.
See **[Connecting an assistant guide](https://docs.kumbuka.ai/get-started/connecting-an-assistant/)** for
the walkthrough, and the
[`kumbuka-server` guide](https://github.com/kumbuka-ai/kumbuka-server#connecting-claude-clients)
for Claude Desktop, Claude Code, and Claude Mobile.
## MCP tools at a glance
Served over **Streamable HTTP** at `/mcp`, scoped to the authenticated user. The
tool names are kept functional on purpose โ the model reads them, and clarity
beats brand noise.
| Tool | What it does |
|---|---|
| `memory_remember` | Write or append an entry (upsert on `key`). Caller picks `scope`, `type`, optional `key`. |
| `memory_recall` | Read entries with filters: `scope`, `type`, substring `query`, optional `include_global`. |
| `memory_forget` | Remove an entry by `id` or by `(scope, key)`. |
| `memory_scopes` | List the scopes the caller may see (their private scope plus shared ones). |
| `memory_load_context` | A typed, ready-to-inject digest of the relevant rules, grouped by type. |
Full reference: **[MCP tools reference](https://docs.kumbuka.ai/reference/mcp-tools/)**.
## Architecture
A single Docker Compose stack. The **Quarkus / Java 21 backend** is the only
component that talks to the identity provider; it serves both the `/mcp` surface
and the admin REST API. **Keycloak** (headless, OAuth 2.1) is the IdP; the
console is a **BFF** client and never holds tokens. **PostgreSQL** is the system
of record (Flyway migrations). **Caddy** is the edge.
```mermaid
flowchart TD
subgraph clients[AI clients]
A["claude.ai ยท Desktop ยท Code ยท Mobile"]
end
B[Browser ยท admin console]
A -- "OAuth 2.1 + bearer token" --> E
B --> E
E[Caddy edge]
E -- "/mcp (Streamable HTTP)" --> S
E -- "/api/* (admin REST)" --> S
E -- "/ (console UI)" --> N
E -- "/auth/* (redirect)" --> K
S["Quarkus backend