Kagura Memory Cloud

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.

Works with Claude, ChatGPT, Gemini, Muse, and other MCP-compatible clients.

Python SDK (KaguraClient, REST clients & FileIngestor)

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.git

cd memory-cloud ./setup.sh

With Claude Code:

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

cd memory-cloud claude # then run /setup

Step-by-step setup:

# 1. Clone

git clone https://github.com/kagura-ai/memory-cloud.git cd memory-cloud

2. Configure environment (generates secrets, prompts for API keys)

(cd backend && python3 -m src.cli.setup_env)

3. Start all services

docker 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.

Platform-specific notes

• WSL (Windows): Install Docker Desktop for Windows and enable WSL integration
• macOS: Install Docker Desktop for Mac. brew install python@3.11 node
• Linux (Ubuntu/Debian): sudo apt install docker.io docker-compose-v2 python3.11 nodejs npm
• GCP (Production): Set production values in .env.local (DATABASE_URL, QDRANT_URL, ENVIRONMENT=production, CORS_ORIGINS) and private values for API_KEY_SECRET, AUDIT_HMAC_KEY, AUDIT_PSEUDO_SALT (openssl rand -hex 32) — the API refuses to start on the defaults or .env.example placeholders
• Frontend env vars: Copy frontend/.env.example to frontend/.env.local and set:
• NEXT_PUBLIC_API_URL — backend URL (default: http://localhost:8080)
• NEXT_PUBLIC_APP_URL — frontend URL for metadata
• NEXT_PUBLIC_PLAN_FREE_DISPLAY_NAME / BASIC / PRO / PROMAX — plan display name customiza