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, and any MCP-compatible client. Python SDK (KaguraClient / KaguraAgent)

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. | | 50 MCP Tools | Memory, Agent Substrate, Neural edges, Contexts, Tags, Files (R2), Analyses (broadlistening), 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](docs/neural-memory-evaluation.md)). 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](docs/deployment.md#embedded-vector-backend-kagura-lite-preview).

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.

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 — plan display name customization (default: S/M/L)

MCP Client Setup

Claude Code (Recommended)

Claude Code + Kagura Memory Cloud gives your AI assistant persistent, searchable, team-shareable memory that works across sessions, machines, and projects.

Why not just use Claude Code's built-in memory?

| | Claude Code Memory | Kagura Memory Cloud | |---|---|---| | Storage | Local files (~/.claude/) | Cloud (PostgreSQL + Qdrant) | | Search | File name only | Hybrid Search (semantic + full-text) | | Sharing | Single machine | Team workspace with RBAC | | Structure | Flat markdown | 3-layer architecture + Neural Memory graph | | Cross-project | Per-project only | Any project via MCP |

Setup (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

1. Restart Claude Code and verify:

You: "List my memory contexts"
→ AI calls list_contexts()

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). > Place in project root for per-project config, or ~/.claude/.mcp.json for global access.

Auto-sync Claude Code memory to Kagura (optional)

Kagura Memory Cloud includes a hook that automatically syncs Claude Code's local memory files to the cloud whenever they're updated. This means your local ~/.claude/ memories are also searchable via Hybrid Search and shared with your team.

Add these environment variables to .env.local:

KAGURA_MCP_URL=http://localhost:8080/mcp/w/{workspace_id}
KAGURA_MCP_TOKEN=kagura_{your_api_key}
KAGURA_CONTEXT_ID={context_id}  # optional — auto-detected from project name if omitted

The sync hook is pre-configured in .claude/settings.json and runs automatically on every memory file write.

Claude Code integration templates (copy to your project)

This repo's .claude/ directory is a ready-to-use template for integrating Kagura Memory Cloud into any project. Copy what you need:

Slash commands — drop into your project's .claude/commands/:

/recall    → Search past knowledge via MCP
/remember   → Save decisions, patterns, learnings via MCP
/guide            → Show setup and usage guide

Hooks (.claude/settings.json) — auto-configured safety guards:

Auto-format    → ruff (Python) / prettier (TypeScript) on every save
Secret detect  → Blocks hardcoded API keys or passwords
SQL injection  → Blocks f-string SQL (enforces parameterized queries)
Memory sync    → Auto-syncs Claude Code memory files to Kagura Cloud

Agents (.claude/agents/) — specialized sub-agents:

code-reviewer  → Read-only code review against project standards
test-runner    → Run tests, diagnose failures, auto-fix

Rules (.claude/rules/) — auto-loaded project conventions:

backend.md     → FastAPI/Python patterns, async, testing
frontend.md    → Next.js/TypeScript, Tailwind, SWR
security.md    → Auth, RBAC, SQL safety, CORS

All of these are designed to work together with Kagura Memory Cloud MCP tools. Adapt them for your own project by editing the prompts and context IDs.

Claude Code Plugin (use Kagura in any project)

The kagura-memory plugin adds session management and memory workflow skills to Claude Code. Install it once and use it across all your projects.

Install:

# From marketplace
/plugin marketplace add kagura-ai/memory-cloud
/plugin install kagura-memory@kagura-memory-cloud

Available skills:

| Skill | Description | |-------|-------------| | /kagura-memory:session-start | Restore previous session context on start | | /kagura-memory:session-summary | Save session knowledge before ending | | /kagura-memory:recall | Search past knowledge | | /kagura-memory:remember | Save new knowledge | | /kagura-memory:guide | Usage guide, connection status, and setup help | | /kagura-memory:smoke-test | Verify all MCP tools work |

Recommended workflow:

/kagura-memory:session-start       # ← Start here: restore context from last session
  ... work normally ...
/kagura-memory:recall              # Search past decisions, patterns, fixes
/kagura-memory:remember            # Save important learnings as you go
  ... finish work ...
/kagura-memory:session-summary     # ← End here: save session knowledge for next time

Skills wrap the raw MCP tools (recall, remember, etc.) with workflow logic — context selection, git state analysis, and structured prompts. Use skills for session management and guided workflows; use MCP tools directly for fine-grained operations.

Run /kagura-memory:guide for setup help and an optional SessionStart hook you can add to your project.

> Prerequisite: MCP connection must be configured (.mcp.json with API key). Run /kagura-memory:guide in your project to set it up.

WSL2 + Claude Code (NAT networking note)

If you run Claude Code inside WSL2 and use the OAuth flow (not the API-key setup above), the browser callback can fail silently: WSL2's default nat mode isolates localhost between Windows and WSL, so the Windows browser's redirect to localhost: never reaches Claude Code's listener inside WSL. This is a WSL networking issue, not a Kagura server bug — the resolved server-side cousin was #689 / PR #692.

Quick fixes:

• Enable mirrored networking — set networkingMode=mirrored in C:\Users\\.wslconfig, then wsl --shutdown (requires WSL 2.0.0+ on Windows 11 22H2+).
• Use API key (Bearer) auth — the .mcp.json setup above skips the OAuth callback entirely.
• Use the device flow (#635 / PR #636, RFC 8628) if your client supports it.

See [Troubleshooting → WSL2 + Claude Code](docs/troubleshooting.md#wsl2--claude-code--mcp-oauth-callback-fails-default-nat-networking) for the full symptom → diagnosis → fix walkthrough.

Claude Desktop / Claude Chat (Web)

Claude Desktop: Same .mcp.json format as Claude Code — place in your project root or ~/.claude/.mcp.json.

Claude Chat (claude.ai): Add as a remote MCP server in Settings > Integrations:

1. Click "Add Integration" → "Custom MCP Server"
2. Enter the MCP end

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kagura-ai
• Source: kagura-ai/memory-cloud
• License: Apache-2.0
• Homepage: https://www.kagura-ai.com

Install and usage instructions live in the source repository linked above.