Memory Cloud

English · 日本語

Self-hosted LLM Knowledge Base for teams — beyond RAG.

MCP-as-compile-API + Hebbian learning + Sleep Maintenance.

Karpathy's LLM Wiki pattern, scaled for teams and persistence.

Works with Claude, ChatGPT, Gemini, and any MCP-compatible client.

Python SDK (KaguraClient / KaguraAgent)

为什么选择神乐记忆云？

每次对话后，你的AI都会忘记一切。神乐解决了这个问题，每次搜索都会变得更聪明。

大多数AI记忆工具只是带有聊天包装的矢量数据库。神乐是不同的——它实现了完整的 LLM知识库 模式（Karpathy的 LLM维基)在团队规模上：

建筑

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知识库——五层实现

Karpathy的 LLM Wiki模式 描述了一个超越传统RAG的5层“活知识库”。神乐在团队规模上实现了所有5层：

复合回路：当前显式（用户/代理调用 remember() 在合成答案之后）。自动回写合成答案是有意选择的，以保持低噪音。

自适应记忆：两条搜索路径

神乐分离 精确搜索 和 发现 分为两条独立的路径，每条路径都针对其目的进行了优化：

recall()  ──→ Hybrid Search (semantic + BM25) ──→ [Reranker] ──→ Precise results
                      │
                      └──→ Hebbian Learning (background) ──→ Graph edges grow
                                                                │
explore() ──→ Graph Traversal (Neural Memory) ←─────────────────┘  Related discoveries

• recall() --精确搜索。混合（语义60%+BM25 40%），可选AI重新排序。返回最相关的记忆。
• explore() --发现。遍历神经记忆图，找到关键字搜索会错过的相关记忆。
• 赫比学习法 --每一个 recall() 默默地强化了共同检索记忆之间的边缘。不需要明确的训练——当你使用系统时，图表会自然增长。

这种分离是有意的：将图形信号混合到回忆中会降低精确度(通过基准验证).相反，每条路都做它最擅长的事情。

数据隔离： 所有数据均按以下方式过滤 workspace_id → context_id → user_id记忆从不跨越国界。带有效载荷过滤的单Qdrant收集。

技术栈： FastAPI（异步）·PostgreSQL·Qdrant·Redis·Next.js 16·OAuth2·基于流式HTTP的MCP

快速开始

系统要求

||最低|推荐| |--|---------|-------------| |CPU |2核|4+核| |RAM | 4 GB | 8+GB| |磁盘| 10 GB可用| 20+GB可用|

先决条件

• Docker&Docker编写
• Python 3.11+
• Node.js 20+
• OpenAI API密钥（用于嵌入）-或Ollama用于本地嵌入
• OAuth2凭据（可选——密码+MFA登录，无需OAuth）

设置

单线设置：

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

使用克劳德代码：

git clone https://github.com/kagura-ai/memory-cloud.git
cd memory-cloud
claude   # then run /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 设置 （由自动配置 setup_env):

\*要么 OPENAI_API_KEY 或者需要一个正在运行的Ollama实例来实现内存功能。

管理员CLI

逃离 backend/ 目录。Docker API容器必须正在运行。

Platform-specific notes

• WSL（Windows）：安装适用于Windows的Docker Desktop并启用WSL集成
• macOS：安装适用于Mac的Docker桌面。 brew install python@3.11 node
• Linux（Ubuntu/Debian）: sudo apt install docker.io docker-compose-v2 python3.11 nodejs npm
• GCP（生产）：在中设置生产值 .env.local (DATABASE_URL, QDRANT_URL, ENVIRONMENT=production, CORS_ORIGINS)
• 前端环境变量：复制 frontend/.env.example 到 frontend/.env.local 并设置：

- NEXT_PUBLIC_API_URL --后端URL（默认值： http://localhost:8080) - NEXT_PUBLIC_APP_URL --元数据的前端URL - NEXT_PUBLIC_PLAN_FREE_DISPLAY_NAME / BASIC / PRO --计划显示名称自定义（默认：S/M/L）

MCP客户端设置

克劳德代码（推荐）

克劳德代码+神乐记忆云为您的AI助手 持久、可搜索、团队共享的内存 它适用于会话、机器和项目。

为什么不直接使用Claude Code的内置内存呢？

设置（3个步骤）：

1. 启动服务并打开 http://localhost:3000/workspace/integrations/api-keys 创建API密钥
2. 复制 .mcp.json.example 到 .mcp.json 并填写您的工作区ID和API密钥：

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

1. 重新启动Claude Code并验证：

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 在...里 .gitignore -永远不要提交（包含API密钥）。 将每个项目配置放置在项目根目录中，或 ~/.claude/.mcp.json 全球访问。

Auto-sync Claude Code memory to Kagura (optional)

神乐记忆云包括一个钩子 自动同步 Claude Code的本地内存文件在更新时都会上传到云端。这意味着你的本地 ~/.claude/ 记忆也可以通过混合搜索进行搜索，并与您的团队共享。

将这些环境变量添加到 .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

同步挂钩已在中预先配置 .claude/settings.json 并在每次写入内存文件时自动运行。

Claude Code integration templates (copy to your project)

此回购 .claude/ 目录是 即用型模板 用于将神乐记忆云集成到任何项目中。复制您需要的内容：

斜杠命令 --进入你的项目 .claude/commands/:

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

钩子 (.claude/settings.json)--自动配置的安全防护装置：

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

代理 (.claude/agents/)--专业分代理：

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

规则 (.claude/rules/)--自动加载的项目约定：

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

所有这些都是为了与神乐内存云MCP工具协同工作而设计的。通过编辑提示和上下文ID，使其适应您自己的项目。

Claude Code Plugin (use Kagura in any project)

这 神乐存储器 该插件为Claude Code添加了会话管理和内存工作流技能。只需安装一次，即可在所有项目中使用它。

安装：

# 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

技能包装原始MCP工具(recall, remember等）与工作流逻辑——上下文选择、git状态分析和结构化提示。使用会话管理和指导工作流程的技能；直接使用MCP工具进行细粒度操作。

跑 /kagura-memory:guide 有关安装帮助和可选的SessionStart挂钩，您可以将其添加到项目中。

先决条件： 必须配置MCP连接(.mcp.json 使用API密钥）。跑 /kagura-memory:guide 在你的项目中设置它。

克劳德桌面/克劳德聊天（网络）

克劳德桌面版：相同 .mcp.json 格式为Claude Code——放在项目根目录中或 ~/.claude/.mcp.json.

克劳德·查特（Claude.ai）：在“设置”>“集成”中添加为远程MCP服务器：

1. 点击“添加集成”→ “自定义MCP服务器”
2. 输入MCP端点URL： https://your-domain.com/mcp/w/{workspace_id}
3. 添加 Authorization: Bearer kagura_{your_api_key} 头球

Claude Chat需要一个可公开访问的URL（不是 localhost).使用生产部署或隧道（例如ngrok、Cloudflare隧道）。

ChatGPT桌面

ChatGPT桌面应用程序支持MCP服务器。通过设置>MCP服务器添加：

1. 服务器URL: https://your-domain.com/mcp/w/{workspace_id}
2. 身份验证：承载令牌 kagura_{your_api_key}

与Claude Chat一样，ChatGPT需要一个公共URL。对于本地开发，请直接使用隧道或REST API。

Gemini CLI

添加 .gemini/settings.json （项目根或 ~/.gemini/settings.json):

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

其他MCP客户端/REST API

任何兼容MCP的客户端都可以通过Streamable HTTP进行连接。对于不支持MCP的客户端，请直接使用REST API：

# 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

MCP工具

9个类别的37个工具。工作区角色： 所有者 >管理员>会员> 观众 （只读）。上下文角色： 所有者 >编辑器>查看器。私有上下文仅对创建者可见。成员可以通过allowlist被限制在特定的上下文中。

内存（6）

神经边缘（4）

背景（7）

标签（1）

文件/R2附件（5）

分析——广泛倾听（5）

将记忆聚类成主题（口口艾式UMAP+KMeans+LLM标记），用于大规模定性分析。

资源——外部数据摄入（5）

睡眠维护（3）

记忆的背景巩固（衰退、边缘修剪、主题总结）。

用法（1）

REST API

除了MCP工具外，还提供了完整的REST API：

• 记忆：记住、回忆、参考、忘记、探索(/api/v1/memory/*)
• 上下文：CRUD，搜索设置(/api/v1/contexts/*)
• 附件：文件上传/下载以供记忆(/api/v1/attachments/*，5MB限制）
• 工作区：管理层、成员、邀请(/api/v1/workspaces/*)
• 管理员：用户、计划管理、神经配置(/api/v1/admin/*)

API完整文档： http://localhost:8080/redoc

认证

支持两个OAuth2提供程序：

• 谷歌OAuth2 --必需。集 GOOGLE_CLIENT_ID 和 GOOGLE_CLIENT_SECRET
• GitHub OAuth2 --可选。集 GITHUB_CLIENT_ID 和 GITHUB_CLIENT_SECRET

跨提供商具有相同电子邮件地址的用户共享一个帐户。

计划层定制

计划控制每个工作区的资源限制。默认值：

通过环境变量进行覆盖：

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

对于自托管单用户设置，请将L（Pro）计划分配给您的工作区。计划变更包括 仅限管理员 默认情况下。对于具有自助计费的SaaS部署，请启用Stripe：

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

用Claude Code开发

该项目旨在开发 随着 克劳德代码和神乐记忆云本身。

Claude Code入门

1. 安装Claude代码

1. 克隆仓库并启动服务（请参阅 快速开始)

1. 在Web UI中创建API键(http://localhost:3000)

1. 创建 .mcp.json 在项目根目录中（请参见 Claude代码设置)

> .mcp.json 在...里 .gitignore -从不提交（包含API密钥）

1. 在克劳德代码中验证：

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

1. 预配置的工具从以下位置自动加载 .claude/:

斜杠命令

挂钩（自动安全防护装置）

• 自动格式化：每个文件保存时都使用Python（ruff）/TypeScript（更漂亮）
• 秘密侦查：阻止包含硬编码API密钥或密码的提交
• SQL注入预防：阻止f-string SQL查询（强制执行SQLAlchemy）
• .env保护：防止意外修改.env文件
• 移民保护：防止修改锁文件
• 内存同步：自动将Claude Code内存文件同步到神乐内存云(详情)

代理

• 代码审查员：根据项目标准进行只读代码审查（在Sonnet上运行）
• 测试工具相关：测试执行、故障诊断和自动修复（在Sonnet上运行）

规则（自动加载上下文）

• rules/backend.md：FastAPI/Python模式、异步要求、测试约定
• rules/frontend.md：Next.js/TypeScript模式、顺风、SWR约定
• rules/security.md：身份验证要求、RBAC、SQL安全、CORS策略

文档

API 参考 --两个互补的切入点：

• 概念（降价）: API 参考 --auth、基本URL、MCP端点、请求/响应示例
• 端点参考（实时）: http://localhost:8080/redoc --由FastAPI自动生成，始终与正在运行的后端同步

概念和指南：

• 核心概念 --工作空间、上下文、记忆、神经记忆、MCP工具
• 建筑 --系统设计和数据流
• 入门指南 --详细的设置指南
• 分块指南 --内存存储的最佳实践
• 资源代币指南 --通过资源令牌接收外部数据
• 神经记忆评估 --基准结果、架构决策
• 搜索质量基准 --准确性测试、重新排序、最佳实践
• 部署 --使用Caddy反向代理进行生产部署
• 贡献 --开发设置、代码风格、PR工作流程
• 安全 --漏洞报告、安全设计
• 开发包 — KaguraClient 和 KaguraAgent 对于Python
• 项目现场: 网站：www.kagura-ai.com --概述、用例、入门路径

花旗日语指南/Japan ese Guide

Claude Code プラグインの使い方

安装

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

可用技能

技能｜说明｜ |--------|------| | /kagura-memory:session-start 还原上一个会话上下文 | /kagura-memory:session-summary 在会话结束前保存知识 | /kagura-memory:recall 查找过去的知识 | /kagura-memory:remember 保存新知识 | /kagura-memory:guide ｜使用指南、连接确认、设置｜ | /kagura-memory:smoke-test ｜确认所有MCP工具的动作｜

建议工作流

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

技能是MCP工具（recall, remember 中描述的场景，使用下列步骤创建明细表，以便在概念设计中分析体量的周长。包含上下文选择、git状态分析和结构化提示。在会话管理和指导工作流中使用技能，在详细操作中使用MCP工具。

前提条件: 需要设置MCP连接（.mcp.json ），模板名称将采用不同的格式。在项目中 /kagura-memory:guide 中所述修改相应参数的值。

贡献

看 贡献.md 用于开发设置、代码风格和PR工作流。

许可证

Apache许可证2.0