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.

---

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 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 repository:

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, which also covers prerequisites, first run, and the kumbuka-server runbook 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 for the walkthrough, and the kumbuka-server guide 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.

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.

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<br/>resource server + BFF"]
    N["Next.js admin console<br/>(BFF client, no tokens)"]
    K["Keycloak<br/>(headless, OAuth 2.1)"]
    P["PostgreSQL<br/>(system of record)"]

    N -- "session cookie" --> S
    S -- "OIDC: bearer + confidential" --> K
    S -- "JDBC + Flyway" --> P

The backend plays two OIDC roles: a bearer resource server for /mcp, and a confidential web-app client (BFF) for the console. Details and the data flow are in Architecture guide.

Repo map

Repo	What it is
kumbuka	This repo — the project front door and public documentation.
kumbuka-server	The Quarkus backend, the MCP surface, Keycloak realm/theme, and the Docker Compose stack you deploy.
kumbuka-console	The Next.js admin console (the team-facing UI).

Documentation

The full documentation site lives at docs.kumbuka.ai (English and German).

Guide	For
Overview	What kumbuka is and the personal/shared boundary.
Concepts	The domain model: scopes, the entry taxonomy, authorship, keys.
Quickstart	Self-hosting the Community Edition, step by step.
Connecting an assistant	Adding the connector in claude.ai.
MCP tools	Reference for the five memory_* tools.
Architecture	Topology, the two OIDC roles, components, data flow.
Security & privacy	The private guarantee, structurally enforced; disable vs. erasure.
Configuration	Env/config knobs and policies.
Editions	Community Edition vs. the commercial path.

License

kumbuka is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). Because kumbuka is typically deployed as a network-accessible service, AGPL §13 applies: if you run a modified version and let users interact with it over a network, you must offer those users the corresponding source of your modified version.

A commercial dual-license path is planned for organizations that cannot operate under the AGPL or that want the commercial-edition features (see Editions). It is not yet generally available — no prices or dates yet.

Contributing

Contributions are welcome. Start with CONTRIBUTING.md for how to contribute and where the per-repo dev setup lives. To report a security issue, see SECURITY.md — please do not open a public issue for vulnerabilities.