Kagura Memory Cloud README

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:

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

* 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 CLI, and any Streamable-HTTP MCP client.

Claude Code (3 steps):

1. Start services and open http://localhost:3000/workspace/integrations/api-keys to create an API key
2. Copy .mcp.json.example to .mcp.json and fill in your workspace ID and API key:

cp .mcp.json.example .mcp.json
# Edit .mcp.json — set workspace_id (from URL bar) and API key

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

• All tools (default): http://localhost:8080/mcp/w/{workspace_id}
• Core tools only — smaller tool list: http://localhost:8080/mcp/w/{workspace_id}?profile=core

Pick core when your client loads every tool schema at session start (it is about 65% smaller). It lists the 12 memory and context tools and leaves out Sleep, analyses, files, edges, secrets, resources and the agent control plane — those stay callable, they are just not listed; switch back to the default URL to see them. 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

64 tools across 13 categories: Memory (remember / recall / explore …), Agent Substrate (pinned + time-triggered delivery, 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 64: the core URL above (?profile=core) lists 12, 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 64 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