{
  "markdown": "<div align=\"center\">\n\n<img src=\"assets/brand/kumbuka-mark-orange.svg\" width=\"88\" alt=\"kumbuka\">\n\n# kumbuka\n\n**Shared, persistent memory for AI assistants working with a team —\nserved over MCP, curated through an admin console, with a private space that stays private.**\n\n[![CI](https://img.shields.io/github/actions/workflow/status/kumbuka-ai/kumbuka/ci.yml?style=flat-square&label=CI&color=FF5B1F)](https://github.com/kumbuka-ai/kumbuka/actions/workflows/ci.yml)\n![License](https://img.shields.io/badge/license-AGPL_v3-FF5B1F?style=flat-square)\n![MCP](https://img.shields.io/badge/MCP-Streamable_HTTP-FF5B1F?style=flat-square)\n![Private memory](https://img.shields.io/badge/private_memory-structurally_guaranteed-141820?style=flat-square&labelColor=FF5B1F)\n![Model](https://img.shields.io/badge/model-open--core-2D4059?style=flat-square)\n![Status](https://img.shields.io/badge/status-pre--beta-C07B1E?style=flat-square)\n![Works with](https://img.shields.io/badge/works_with-Claude_%26_MCP_clients-FF5B1F?style=flat-square)\n\n</div>\n\n> **Status: pre-beta.** kumbuka is in active development. The architecture and\n> data model are settled and the private-memory guarantee is a hard design\n> constraint, but the project is not yet a hardened, shipped product. Expect\n> rough edges and breaking changes.\n\n*kumbuka* is Swahili — the imperative **\"remember!\"**. The project lives at\n[kumbuka.ai](https://kumbuka.ai).\n\n---\n\n## The problem: the context tax\n\nAI assistants are stateless between sessions. A team using them pays the same\ntoll over and over — re-explaining the things that should simply be known:\n\n- *\"We use Postgres as the system of record.\"*\n- *\"Money is integer minor units, never floats.\"*\n- *\"Service names are kebab-case.\"*\n\nThat steering knowledge — the decisions, conventions, and constraints that\nshape how an assistant should work — is exactly what an assistant ought to\n*remember* and apply without being told again. Today it lives in people's heads\nand in scattered chat history, so every new session starts from zero.\n\n## What kumbuka is\n\nkumbuka makes that knowledge a first-class, team-owned asset. It gives a team a\ndurable, shared place for the rules an assistant should carry across\nconversations, and serves them to any MCP-capable assistant (Claude and others)\nover a remote **MCP server**. A web **admin console** lets the team curate the\nshared memory.\n\nIt is deliberately **not** a document store or a RAG index. kumbuka holds\n*work-steering knowledge* — a small, typed set of decisions, conventions,\nconstraints, definitions, open questions, and status — not a copy of your docs\nor source, which stay in their own systems.\n\n- **Shared and curatable** — the team sees and edits what the assistant relies\n  on, instead of each person accumulating an opaque, divergent context.\n- **Portable** — any MCP-capable assistant reads and writes it through one\n  endpoint.\n- **Bounded** — a fixed taxonomy and explicit scopes keep the memory legible\n  rather than letting it sprawl.\n\n## The private-memory guarantee\n\n> **A member's private memory is theirs alone.** It is reachable only by them,\n> only over their own authenticated MCP session. **No admin, no console screen,\n> and no team-facing API can read it.**\n\nThis is the backbone of the product, not a feature flag. It is enforced at the\n**data-access layer** — the privileged (admin/console) code paths have no route\nthat can return private rows — **not** by a configuration toggle that could be\nflipped. Disabling a member suspends their account but leaves their private\nmemory untouched and theirs.\n\nSee [the Security & privacy guide](https://docs.kumbuka.ai/operations/security/) for how this is structurally enforced.\n\n## Quickstart (self-host the Community Edition)\n\nThe Community Edition is the free, self-hosted, single-tenant memory core. It\nruns as a single Docker Compose stack (backend · PostgreSQL · Keycloak · Caddy).\nThe deployable stack lives in the\n[`kumbuka-server`](https://github.com/kumbuka-ai/kumbuka-server) repository:\n\n```bash\ngit clone https://github.com/kumbuka-ai/kumbuka-server\ncd kumbuka-server\ncp .env.example .env                  # set your domain + secrets\ndocker compose --profile app up -d    # backend + postgres + keycloak + caddy\n```\n\nThe admin console is a separate service, added to the same stack via a small\n`compose.override.yml` — see the step-by-step\n**[Quickstart guide](https://docs.kumbuka.ai/get-started/quickstart/)**, which also covers prerequisites,\nfirst run, and the [`kumbuka-server` runbook](https://github.com/kumbuka-ai/kumbuka-server#quick-start-dev)\nfor production deployment.\n\n## Connect your assistant\n\nkumbuka is reached by AI clients as a **custom MCP connector** — the endpoint\nURL is all a client needs; there is no client id and no client secret. In\nclaude.ai you add it under **Settings → Connectors**, sign in once through the\nOAuth flow, and your assistant can then call the memory tools on your behalf,\nincluding your own private scope.\n\nSee **[Connecting an assistant guide](https://docs.kumbuka.ai/get-started/connecting-an-assistant/)** for\nthe walkthrough, and the\n[`kumbuka-server` guide](https://github.com/kumbuka-ai/kumbuka-server#connecting-claude-clients)\nfor Claude Desktop, Claude Code, and Claude Mobile.\n\n## MCP tools at a glance\n\nServed over **Streamable HTTP** at `/mcp`, scoped to the authenticated user. The\ntool names are kept functional on purpose — the model reads them, and clarity\nbeats brand noise.\n\n| Tool | What it does |\n|---|---|\n| `memory_remember` | Write or append an entry (upsert on `key`). Caller picks `scope`, `type`, optional `key`. |\n| `memory_recall` | Read entries with filters: `scope`, `type`, substring `query`, optional `include_global`. |\n| `memory_forget` | Remove an entry by `id` or by `(scope, key)`. |\n| `memory_scopes` | List the scopes the caller may see (their private scope plus shared ones). |\n| `memory_load_context` | A typed, ready-to-inject digest of the relevant rules, grouped by type. |\n\nFull reference: **[MCP tools reference](https://docs.kumbuka.ai/reference/mcp-tools/)**.\n\n## Architecture\n\nA single Docker Compose stack. The **Quarkus / Java 21 backend** is the only\ncomponent that talks to the identity provider; it serves both the `/mcp` surface\nand the admin REST API. **Keycloak** (headless, OAuth 2.1) is the IdP; the\nconsole is a **BFF** client and never holds tokens. **PostgreSQL** is the system\nof record (Flyway migrations). **Caddy** is the edge.\n\n```mermaid\nflowchart TD\n    subgraph clients[AI clients]\n      A[\"claude.ai · Desktop · Code · Mobile\"]\n    end\n    B[Browser · admin console]\n\n    A -- \"OAuth 2.1 + bearer token\" --> E\n    B --> E\n\n    E[Caddy edge]\n    E -- \"/mcp (Streamable HTTP)\" --> S\n    E -- \"/api/* (admin REST)\" --> S\n    E -- \"/ (console UI)\" --> N\n    E -- \"/auth/* (redirect)\" --> K\n\n    S[\"Quarkus backend<br/>resource server + BFF\"]\n    N[\"Next.js admin console<br/>(BFF client, no tokens)\"]\n    K[\"Keycloak<br/>(headless, OAuth 2.1)\"]\n    P[\"PostgreSQL<br/>(system of record)\"]\n\n    N -- \"session cookie\" --> S\n    S -- \"OIDC: bearer + confidential\" --> K\n    S -- \"JDBC + Flyway\" --> P\n```\n\nThe backend plays **two OIDC roles**: a bearer **resource server** for `/mcp`,\nand a confidential **web-app client** (BFF) for the console. Details and the\ndata flow are in **[Architecture guide](https://docs.kumbuka.ai/operations/architecture/)**.\n\n## Repo map\n\n| Repo | What it is |\n|---|---|\n| [`kumbuka`](https://github.com/kumbuka-ai/kumbuka) | This repo — the project front door and public documentation. |\n| [`kumbuka-server`](https://github.com/kumbuka-ai/kumbuka-server) | The Quarkus backend, the MCP surface, Keycloak realm/theme, and the Docker Compose stack you deploy. |\n| [`kumbuka-console`](https://github.com/kumbuka-ai/kumbuka-console) | The Next.js admin console (the team-facing UI). |\n\n## Documentation\n\nThe full documentation site lives at **[docs.kumbuka.ai](https://docs.kumbuka.ai)** (English and German).\n\n| Guide | For |\n|---|---|\n| [Overview](https://docs.kumbuka.ai/get-started/overview/) | What kumbuka is and the personal/shared boundary. |\n| [Concepts](https://docs.kumbuka.ai/concepts/data-model/) | The domain model: scopes, the entry taxonomy, authorship, keys. |\n| [Quickstart](https://docs.kumbuka.ai/get-started/quickstart/) | Self-hosting the Community Edition, step by step. |\n| [Connecting an assistant](https://docs.kumbuka.ai/get-started/connecting-an-assistant/) | Adding the connector in claude.ai. |\n| [MCP tools](https://docs.kumbuka.ai/reference/mcp-tools/) | Reference for the five `memory_*` tools. |\n| [Architecture](https://docs.kumbuka.ai/operations/architecture/) | Topology, the two OIDC roles, components, data flow. |\n| [Security & privacy](https://docs.kumbuka.ai/operations/security/) | The private guarantee, structurally enforced; disable vs. erasure. |\n| [Configuration](https://docs.kumbuka.ai/reference/configuration/) | Env/config knobs and policies. |\n| [Editions](https://docs.kumbuka.ai/concepts/editions/) | Community Edition vs. the commercial path. |\n\n## License\n\nkumbuka is licensed under the **GNU Affero General Public License v3.0**\n([AGPL-3.0](LICENSE)). Because kumbuka is typically deployed as a\nnetwork-accessible service, AGPL **§13** applies: if you run a modified version\nand let users interact with it over a network, you must offer those users the\ncorresponding source of your modified version.\n\nA commercial **dual-license** path is planned for organizations that cannot\noperate under the AGPL or that want the commercial-edition features (see\n[Editions](https://docs.kumbuka.ai/concepts/editions/)). It is not yet generally available — no\nprices or dates yet.\n\n## Contributing\n\nContributions are welcome. Start with **[CONTRIBUTING.md](CONTRIBUTING.md)** for\nhow to contribute and where the per-repo dev setup lives. To report a security\nissue, see **[SECURITY.md](SECURITY.md)** — please do not open a public issue for\nvulnerabilities.\n",
  "bytes": 9973,
  "sha": "b7aa6dbe26b20af5d834d020e7752af1445ff9f6257243939c3056e16d62535c",
  "repo_slug": "kumbuka-ai/kumbuka",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_ai_kumbuka_kumbuka_server_58fa4a14/readme"
}