Kagura Memory Cloud

[Kagura Memory Cloud — adaptive memory for AI agents and teams, beyond RAG]

English · 日本語

Adaptive memory for AI agents and teams — self-hosted, beyond RAG.
An MCP server that gets smarter every time you search:
hybrid search + a neural memory graph that learns which memories belong together.

[License] [CI] [codecov] [Python 3.11+] [Node.js 24+] [MCP] [SafeSkill 90/100]

Works with Claude, ChatGPT, Gemini, and any MCP-compatible client.
Python SDK (KaguraClient, REST clients & FileIngestor)

[Claude Code CLI recalling from Kagura Memory over MCP]
Claude Code CLI recalling memories from Kagura over MCP — ▶ watch the demo

Why Kagura Memory Cloud?

Your AI forgets everything after each conversation. Kagura fixes that — and gets smarter every time you search.

Most AI memory tools are just vector databases with a chat wrapper. Kagura is different — it implements the full LLM Knowledge Base pattern (Karpathy's LLM Wiki) at team scale:

Architecture

Workspace (team/org)├── Context A ("my-project")     ← like a folder│   ├── Memory 1                 ← 3-layer: summary / context / content│   ├── Memory 2│   └── Neural edges (Hebbian)   ← automatic connections├── Context B ("learning-notes")│   └── ...└── Members (Owner/Admin/Member/Viewer)

LLM Knowledge Base — 5-Layer Implementation

Karpathy's LLM Wiki pattern describes a 5-layer "living knowledge base" — beyond traditional RAG. Kagura implements all 5 layers at team scale:

Compounding loop: Currently explicit (user/agent calls remember() after synthesizing answers). Auto-write-back of synthesized answers is intentionally opt-in to keep noise low.

Adaptive Memory: Two Search Paths

Kagura separates precision search and discovery into two independent paths, each optimized for its purpose:

recall()  ──→ Hybrid Search (semantic + BM25) ──→ [Reranker] ──→ Precise results                      │                      └──→ Hebbian Learning (background) ──→ Graph edges grow                                                                │explore() ──→ Graph Traversal (Neural Memory) ←─────────────────┘  Related discoveries

• recall() — Precision search. Hybrid (semantic 60% + BM25 40%) with optional AI reranking. Returns the most relevant memories.
• explore() — Discovery. Traverses the Neural Memory graph to find related memories that keyword search would miss. Opt-in over MCP: ?add_tools=explore or ?profile=full on the URL lists it.
• Hebbian learning — Every recall() silently strengthens edges between co-retrieved memories. No explicit training needed — the graph grows organically as you use the system.

This separation is intentional: mixing graph signals into recall degrades precision (validated via benchmarks). Instead, each path does what it's best at.

Data isolation: All data is filtered by workspace_id → context_id → user_id. Memories never leak across boundaries. Single Qdrant collection with payload filtering.

Tech stack: FastAPI (async) · PostgreSQL · Qdrant · Redis · Next.js 16 · OAuth2 · MCP over Streamable HTTP

Vector backend: Qdrant by default. A single-process self-hosted / CLI / edge deployment can instead run the embedded LanceDB backend — "Kagura Lite" (preview) with no separate Qdrant server (KAGURA_VECTOR_BACKEND=lance, cd backend && uv sync --locked --extra lite). Not for multi-worker / SaaS (LanceDB is single-writer). See Deployment → Embedded Vector Backend.

Quick Start

System Requirements

Prerequisites

• Docker & Docker Compose
• Python 3.11+
• Node.js 24+
• OpenAI API key (for embeddings) — or a self-hosted inference server (e.g. Ollama) for local embeddings
• OAuth2 credentials (optional — password + MFA login available without OAuth)

Setup

One-line setup:

git clone https://github.com/kagura-ai/memory-cloud.gitcd memory-cloud./setup.sh

With Claude Code:

git clone https://github.com/kagura-ai/memory-cloud.gitcd memory-cloudclaude   # then run /setup

Step-by-step setup:

# 1. Clonegit clone https://github.com/kagura-ai/memory-cloud.gitcd memory-cloud
# 2. Configure environment (generates secrets, prompts for API keys)(cd backend && python3 -m src.cli.setup_env)
# 3. Start all servicesdocker compose up -d
# 4. Run migrations(cd backend && alembic upgrade head)
# 5. Create admin account (interactive — sets password, MFA, API key, embedding provider)(cd backend && python3 -m src.cli.create_admin)
# Backend API:  http://localhost:8080# Frontend UI:  http://localhost:3000# API docs:     http://localhost:8080/redoc

.env.local settings (auto-configured by setup_env):

* Either OPENAI_API_KEY or a running self-hosted inference server (e.g. Ollama) is required for memory features.

Admin CLI

Run from backend/ directory. Docker API container must be running.

Connect an MCP Client

Works with Claude Code, Claude Desktop, Claude Chat, ChatGPT, Gemini, Gemini CLI, and any Streamable-HTTP MCP client.

Claude Code (3 steps):

1. Start services and open http://localhost:3000/workspace/integrations/credentials?tab=api-keys to create an API key
2. Copy .mcp.json.example to .mcp.json and fill in your API key (a key created there is scoped to its workspace):

cp .mcp.json.example .mcp.json# Edit .mcp.json — set the API key

.mcp.json.example ships with the all-tools URL. Set "url" to one of:

• Core tools (default): http://localhost:8080/mcp
• All tools: http://localhost:8080/mcp?profile=full

An OAuth client (Claude.ai, Claude Desktop, ChatGPT, Gemini, Cursor, claude mcp add) uses the same /mcp URL and connects to the workspace selected in the web UI; /mcp/w/{workspace_id} pins such a connector to one workspace when you belong to several.

The default URL lists the core memory and context tools (the exact set is under Tool Profiles) and leaves out explore, Sleep, analyses, files, edges, secrets, resources and the agent control plane — they are just not listed — describe_tools names them from inside a session, and most clients let the model call listed tools only, so a task that needs them reconnects with the URL below. Add ?profile=full when your client should see every tool schema up front (the list is about 2.7 times larger). See Tool Profiles.

3. Restart Claude Code and verify:

You: "Remember: our API uses JWT with 1h expiry and refresh token rotation"→ AI calls remember() — stored permanently
You: "What do we know about auth?"→ AI calls recall() — finds it instantly, even months later

.mcp.json is in .gitignore — never commit it (contains API keys).

Full setup guide — every client, the memory-sync hook, the ready-to-use .claude/ templates, the kagura-memory Claude Code plugin (skills + tool-guardrail hooks), and the WSL2 networking note: MCP Client Setup

MCP Tools

72 tools across 14 categories: Guide (guide, the tool manual on demand; describe_tools, the tools the URL left out), Memory (remember / remember_batch / recall / explore …), Agent Substrate (pinned + time-triggered delivery, deterministic list / changes_since, one-call bootstrap, state, measurements, feedback), Agent Control Plane (preview), Neural Edges, Contexts, Tags, Files (R2), Analyses (Memory Analysis), Resources, Secrets (zero-knowledge), Sleep Maintenance, Usage, and API-Key Bindings — each with per-role access control.

Tool-by-tool reference with required roles: MCP Tools Reference

An agent's writes can be listed and undone: changes_since + rollback_session per session (a stateless MCP client can name its own session with _meta["ai.kagura/sessionId"] or a Kagura-Session-Id header), or — for clients without a session id — over a time window of your own writes (by_me=true, since / until); see Which clients get a session id.

A client does not have to list all 72: the default URL above lists the 21 core tools (?profile=full lists everything), ?tools=remember,recall lists exactly the tools you name, and ?add_tools=list_edges lists the core tools plus the ones you name — see Tool Profiles.

REST API

In addition to MCP tools, a full REST API is available:

• Memory: remember, recall, reference, forget, explore (/api/v1/memory/*)
• Contexts: CRUD, search settings (/api/v1/contexts/*)
• Agents (preview): Registry, context bindings, and composed bootstrap (/api/v1/agents/*)
• Files: Presigned upload/download backed by R2 (/api/v1/files/*, up to 100 MiB); legacy /api/v1/attachments/* routes return 410 Gone
• Analyses: Memory Analysis preview/start/read/cancel (/api/v1/analyses/*)
• Resources: External event ingestion and resource inspection (/api/v1/resources/*)
• Workspaces: Management, members, invitations (/api/v1/workspaces/*)
• Admin: Users, plan management, neural config (/api/v1/admin/*)
• Secrets: Zero-knowledge secret store — ciphertext-only, server never decrypts (/api/v1/config/secrets/*)

Full API documentation: http://localhost:8080/redoc

Authentication

Two OAuth2 providers are supported:

• Google OAuth2 — Optional. Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET
• GitHub OAuth2 — Optional. Set GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET

Users with the same email address across providers share a single account. Password + MFA login is available without any OAuth provider (see Quick Start). An existing account can also add a password from its profile and then sign in with its verified email address and that password; see Deployment → Email + password sign-in.

Plan Tier Customization

Plans control per-workspace resource limits (contexts / memories / MCP calls per day). Four tiers ship by default: S (free), M (basic), L (pro) and XL (promax). For self-hosted single-user setups, assign the XL (promax) plan to your workspace — it is the only tier that may create resources, connectors and public contexts (numeric limits are env-overridable; a tier's feature set is not). Defaults, environment-variable overrides, and optional Stripe self-service billing: Deployment → Plan Tiers

Development with Claude Code

This project is designed to be developed with Claude Code and Kagura Memory Cloud itself — pre-configured slash commands, safety hooks, sub-agents, and rules load automatically from .claude/. Setup and the full tooling reference: Contributing → Development with Claude Code

Documentation

API reference — two complementary entry points:

• Concepts (markdown): API Reference — auth, base URLs, MCP endpoint, request/response examples
• Endpoint reference (live): http://localhost:8080/redoc — auto-generated from FastAPI, always in sync with the running backend

Concepts & guides:

• Core Concepts — Workspace, Context, Memory, Neural Memory, MCP Tools
• MCP Client Setup — Claude Code / Desktop / Chat, ChatGPT, Gemini, Gemini CLI, plugin & templates
• MCP Tools Reference — All 72 tools with required roles
• Architecture — System design and data flow
• Getting Started — Detailed setup guide
• Chunking Guide — Best practices for memory storage
• Resource Tokens Guide — External data ingestion via resource tokens
• Neural Memory Evaluation — Benchmark results, architecture decisions
• Search Quality Benchmark — Accuracy tests, reranking, best practices
• Retrieval Feedback & Eval Gate — Feedback signal + the no-self-update-loop policy (Agent Memory Substrate)
• Deployment — Production deployment with Caddy reverse proxy
• Contributing — Development setup, code style, PR workflow
• Security — Vulnerability reporting, security design
• Python SDK — KaguraClient (MCP) plus REST clients for resources, files, secrets, workspaces, and agent bootstrap, and a document FileIngestor
• Project site: www.kagura-ai.com — overview, use cases, getting started paths

Contributing

See CONTRIBUTING.md for development setup, code style, and PR workflow.

License

Apache License 2.0