How do I install Kagura Memory Cloud?

Copy the http config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Kagura Memory Cloud need an API key?

No required environment variable is listed on this record.

What transport does Kagura Memory Cloud use?

Kagura Memory Cloud is reached over HTTP.

When was Kagura Memory Cloud last checked?

Last checked 2026-11-10. Persistent memory for AI assistants: store, search, and connect knowledge across conversations.

Kagura Memory Cloud MCP server

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.
72 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)
`AUDIT_HMAC_KEY` / `AUDIT_PSEUDO_SALT`	Production	Audit-log HMAC key and erasure salt (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.

WSL (Windows): Install Docker Desktop for Windows and enable WSL integration
macOS: Install Docker Desktop for Mac. brew install [email protected] 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 customization (default: S/M/L/XL)

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

Start services and open http://localhost:3000/workspace/integrations/credentials?tab=api-keys to create an API key
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 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.6 times larger). See Tool Profiles.

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 22 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

Kagura Memory Cloud

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Kagura Memory Cloud?

Does Kagura Memory Cloud need an API key?

What transport does Kagura Memory Cloud use?

When was Kagura Memory Cloud last checked?

Documentation

Why Kagura Memory Cloud?

Architecture

LLM Knowledge Base — 5-Layer Implementation

Adaptive Memory: Two Search Paths

Quick Start

System Requirements

Prerequisites

Setup

Admin CLI

Connect an MCP Client

MCP Tools

REST API

Authentication

Plan Tier Customization

Development with Claude Code

Documentation

Contributing

License