memory-cloud

English · 日本語

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.
64 MCP Tools	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, pip install '.[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)

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 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/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).

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