Adaptive AI Memory Platform — Self-hosted, open source.
Give your AI assistants persistent memory that gets smarter as you use it.

Works with Claude, ChatGPT, Gemini, and any MCP-compatible client.
Python SDK (KaguraClient / KaguraAgent)

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:

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)

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

• Docker & Docker Compose
• Python 3.11+
• Node.js 20+
• OpenAI API key (for embeddings) — or Ollama for local embeddings
• OAuth2 credentials (optional — password + MFA login available without OAuth)

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 Ollama instance is required for memory features.

Run from backend/ directory. Docker API container must be running.

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?

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

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.

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

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

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

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

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

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

/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

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 endpoint URL: https://your-domain.com/mcp/w/{workspace_id}
3. Add the Authorization: Bearer kagura_{your_api_key} header

Claude Chat requires a publicly accessible URL (not localhost). Use a production deployment or tunnel (e.g., ngrok, Cloudflare Tunnel).

ChatGPT desktop app supports MCP servers. Add via Settings > MCP Servers:

1. Server URL: https://your-domain.com/mcp/w/{workspace_id}
2. Authentication: Bearer token kagura_{your_api_key}

Like Claude Chat, ChatGPT requires a public URL. For local development, use a tunnel or the REST API directly.

Add to .gemini/settings.json (project root or ~/.gemini/settings.json):

{
  "mcpServers": {
    "kagura-memory": {
      "url": "http://localhost:8080/mcp/w/{workspace_id}",
      "headers": {
        "Authorization": "Bearer kagura_{your_api_key}"
      }
    }
  }
}

Any MCP-compatible client can connect via Streamable HTTP. For clients without MCP support, use the REST API directly:

# Search memories
curl -X POST -H "Authorization: Bearer kagura_{your_key}" \
  -H "Content-Type: application/json" \
  -d '{"query": "your search", "context_id": "..."}' \
  http://localhost:8080/api/v1/memories/search

Workspace roles: Owner > Admin > Member > Viewer (read-only). Context roles: Owner > Editor > Viewer. Private contexts are visible only to the creator. Members may be restricted to specific contexts via allowlist.

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/*)
• Attachments: File upload/download for memories (/api/v1/attachments/*, 5MB limit)
• Workspaces: Management, members, invitations (/api/v1/workspaces/*)
• Admin: Users, plan management, neural config (/api/v1/admin/*)

Full API documentation: http://localhost:8080/redoc

Two OAuth2 providers are supported:

• Google OAuth2 — Required. 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.

Plans control resource limits per workspace. Defaults:

Override via environment variables:

PLAN_FREE_MAX_CONTEXTS=5
PLAN_FREE_MEMORY_LIMIT=5000
PLAN_BASIC_MAX_CONTEXTS=10
PLAN_PRO_MAX_CONTEXTS=50

For self-hosted single-user setups, assign the L (Pro) plan to your workspace. Plan changes are admin-only by default. For SaaS deployments with self-service billing, enable Stripe:

BILLING_ENABLED=true
STRIPE_SECRET_KEY=sk_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_PRICE_BASIC=price_xxx
STRIPE_PRICE_PRO=price_yyy

This project is designed to be developed with Claude Code and Kagura Memory Cloud itself.

1. Install Claude Code

2. Clone the repo and start services (see Quick Start)

3. Create an API key in the Web UI (http://localhost:3000)

4. Create .mcp.json in the project root (see Claude Code setup)

   .mcp.json is in .gitignore — never commit it (contains API keys)

5. Verify in Claude Code:

   > list_contexts()
   > create_context(name="my-project")
   

6. Pre-configured tooling loads automatically from .claude/:

• Auto-format: Python (ruff) / TypeScript (prettier) on every file save
• Secret detection: Blocks commits containing hardcoded API keys or passwords
• SQL injection prevention: Blocks f-string SQL queries (enforces SQLAlchemy)
• .env protection: Prevents accidental modification of .env files
• Migration protection: Prevents modification of lock files
• Memory sync: Auto-syncs Claude Code memory files to Kagura Memory Cloud (details)

• code-reviewer: Read-only code review against project standards (runs on Sonnet)
• test-runner: Test execution, failure diagnosis, and auto-fix (runs on Sonnet)

• rules/backend.md: FastAPI/Python patterns, async requirements, testing conventions
• rules/frontend.md: Next.js/TypeScript patterns, Tailwind, SWR conventions
• rules/security.md: Auth requirements, RBAC, SQL safety, CORS policy

• Core Concepts — Workspace, Context, Memory, Neural Memory, MCP Tools
• Architecture — System design and data flow
• Getting Started — Detailed setup guide
• API Reference — REST API documentation
• 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
• Deployment — Production deployment with Caddy reverse proxy
• Contributing — Development setup, code style, PR workflow
• Security — Vulnerability reporting, security design
• Python SDK — KaguraClient and KaguraAgent for Python

# マーケットプレイスから追加
/plugin marketplace add kagura-ai/memory-cloud
/plugin install kagura-memory@kagura-memory-cloud

/kagura-memory:session-start       # ← ここから：前回のコンテキストを復元
  ... 通常の作業 ...
/kagura-memory:recall              # 過去の設計判断・パターン・修正を検索
/kagura-memory:remember            # 重要な学びを都度保存
  ... 作業完了 ...
/kagura-memory:session-summary     # ← ここで終了：次回のためにセッション知識を保存

See CONTRIBUTING.md for development setup, code style, and PR workflow.

Apache License 2.0