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, and any MCP-compatible client.
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:

Approach	Storage	Compounding	Scale
Vector DB / RAG	Embedded chunks	None — retrieve-only	Any
Karpathy's LLM Wiki	Markdown files	LLM rewrites pages	Personal (~100 pages)
Kagura Memory Cloud	PostgreSQL + Qdrant + Neural graph	Hebbian + Sleep Maintenance	Team / org

Feature	Description
Adaptive Memory	Every search automatically strengthens connections between related memories. The more you use it, the better explore() discovers hidden relationships.
Hybrid Search	Semantic (OpenAI / self-hosted) + BM25 keyword — 96% top-1 accuracy
AI Reranking	Self-hosted (Ollama/vLLM — local, free), Voyage AI, or Cohere — cross-encoder reranking for precision
Neural Memory Graph	Hebbian learning builds a knowledge graph in the background. explore() traverses it for serendipitous discovery.
Agent Memory Substrate	Beyond a knowledge store: delivery modes (pinned / time-triggered), a server-stamped trust boundary, an agent state lane, and a retrieval-feedback signal — the primitives an autonomous agent loop needs.
Agent Control Plane (preview)	Workspace-scoped Agent Registry, subtractive context bindings, agent-bound member keys, lifecycle kill switches, and one-call session bootstrap. Introduced in v0.49.0.
70 MCP Tools	Guide, Memory, Agent Substrate, Agent Control Plane, Neural edges, Contexts, Tags, Files (R2), Analyses (Memory Analysis), Resources, Secrets, Sleep Maintenance, Usage, API-Key Bindings
Multi-Provider	OpenAI or self-hosted (Ollama, vLLM — local, private, zero cost) for embeddings
Team Ready	Workspaces, RBAC, context isolation, shared memory
Web UI	Next.js dashboard — contexts, search settings, member management
5-Minute Setup	./setup.sh and you're done

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:

Layer	Kagura Implementation	Difference from Karpathy's pattern
Ingest	REST /api/v1/memory, MCP remember, R2 file storage, resource tokens	+ binary blobs, + multi-tenant
Compile	MCP-as-compile-API — chat agent compiles via structured tool calls (remember(summary, content, type, tags)) + Sleep Maintenance for batch consolidation	Continuous micro-compile (not batch wiki rewrite) — schema-enforced output
Index	Triple index: BM25 (keyword) + Qdrant (semantic) + Hebbian graph (relational) — all auto-maintained	No manual index.md upkeep
Query	Hybrid Search + AI Reranker + explore graph traversal	Beyond markdown grep — supports semantic + relational queries
Enhance	Hebbian learning — every recall() strengthens edges between co-retrieved memories. Sleep Maintenance consolidates periodically.	Background graph evolution (zero LLM cost) vs LLM-driven page rewrites

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

	Minimum	Recommended
CPU	2 cores	4+ cores
RAM	4 GB	8+ GB
Disk	10 GB free	20+ GB free

Prerequisites

• Docker & Docker Compose
• Python 3.11+
• Node.js 20+
• 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):

Setting	Required	Description
API_KEY_SECRET	Yes	Secret for API key encryption (auto-generated)
JWT_SECRET	Yes	Secret for JWT tokens (auto-generated)
OPENAI_API_KEY	Yes*	OpenAI API key for embeddings
SELF_HOSTED_BASE_URL	No	Self-hosted backend URL (default: http://localhost:11434)
EMBEDDING_PROVIDER	No	openai (default) or self_hosted
GOOGLE_CLIENT_ID/SECRET	No	Google OAuth2 login (optional — password login available)
GITHUB_CLIENT_ID/SECRET	No	GitHub OAuth2 login (optional)

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

Admin CLI

Command	Purpose
python3 -m src.cli.setup_env	Generate secrets + configure .env.local (run before Docker)
python3 -m src.cli.create_admin	Create admin + workspace + API key + .mcp.json + embedding setup
python3 -m src.cli.reset_password	Reset password and/or MFA
python3 -m src.cli.delete_admin	Delete admin (for re-creation)
python3 -m src.cli.transfer_context_creator	Move contexts created by one user to another (CLI admin → OAuth account, see docs/deployment.md)

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)
• 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 customization (default: S/M/L/XL)

Connect an MCP Client

Works with Claude Code, Claude Desktop, Claude Chat, ChatGPT, 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, 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 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.9 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

70 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

A client does not have to list all 70: the default URL above lists the 18 core tools (?profile=full lists everything), and ?tools=remember,recall lists exactly the tools 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 CLI, plugin & templates
• MCP Tools Reference — All 70 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