# Memory Cloud

> Adaptive memory for AI agents & teams — beyond RAG. Self-hosted MCP server that gets smarter every time you search: hybrid search + a neural memory graph that learns. Works with Claude, ChatGPT & any MCP client.

- **Type:** MCP server
- **Install:** `agentstack add mcp-kagura-ai-memory-cloud`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [kagura-ai](https://agentstack.voostack.com/s/kagura-ai)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [kagura-ai](https://github.com/kagura-ai)
- **Source:** https://github.com/kagura-ai/memory-cloud
- **Website:** https://www.kagura-ai.com

## Install

```sh
agentstack add mcp-kagura-ai-memory-cloud
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)) 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](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) 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:**

```bash
git clone https://github.com/kagura-ai/memory-cloud.git
cd memory-cloud
./setup.sh
```

**With Claude Code:**

```bash
git clone https://github.com/kagura-ai/memory-cloud.git
cd memory-cloud
claude   # then run /setup
```

**Step-by-step setup:**

```bash
# 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:

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

3. 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`:

```bash
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:**

```bash
# 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](https://github.com/kagura-ai/memory-cloud/pull/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](https://github.com/kagura-ai/memory-cloud/pull/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](https://github.com/kagura-ai)
- **Source:** [kagura-ai/memory-cloud](https://github.com/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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** yes

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-kagura-ai-memory-cloud
- Seller: https://agentstack.voostack.com/s/kagura-ai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.