Kagura Memory Cloud

English · 日本語

为 AI Agent 和团队提供自适应记忆 — 可自托管，超越 RAG。
一个 MCP 服务，每次搜索都会变得更智能：
混合搜索 + 神经记忆图谱，能够学习哪些记忆彼此相关。

兼容 Claude、ChatGPT、Gemini 及任何兼容 MCP 的客户端。
Python SDK（KaguraClient、REST 客户端和 FileIngestor）

Claude Code CLI 通过 MCP 从 Kagura 中回忆记忆 — ▶ 观看演示

## 为什么选择 Kagura Memory Cloud？

你的 AI 会在每次对话结束后忘记一切。Kagura 能解决这个问题，而且每次搜索都会变得更聪明。

大多数 AI 记忆工具只是套了聊天界面的向量数据库。Kagura 与众不同——它在团队规模上实现了完整的 大模型知识库 模式（Karpathy 的 大模型 Wiki）：

方案	存储	累积提升	规模
向量数据库 / RAG	嵌入后的文本块	无——仅检索	任意
Karpathy 的大模型 Wiki	Markdown 文件	大模型重写页面	个人（约 100 个页面）
Kagura Memory Cloud	PostgreSQL + Qdrant + 神经图	赫布学习 + 睡眠维护	团队 / 组织

功能	描述
自适应记忆	每次搜索都会自动强化相关记忆之间的连接。使用得越多，explore() 就越能发现隐藏的关联。
混合搜索	语义搜索（OpenAI / 可自托管）+ BM25 关键词搜索——Top-1 准确率达 96%
AI 重排序	可自托管（Ollama/vLLM——本地、免费）、Voyage AI 或 Cohere——通过交叉编码器重排序提升精准度
神经记忆图	赫布学习会在后台构建知识图谱。explore() 会遍历图谱，带来意外发现。
Agent 记忆基底	不只是知识存储：提供投递模式（固定 / 按时间触发）、由服务端标记的信任边界、Agent 状态通道，以及检索反馈信号——这些都是自主 Agent 循环所需的基础组件。
Agent 控制平面（预览）	限定于工作区的 Agent 注册表、可减除的上下文绑定、绑定到 Agent 的成员密钥、生命周期终止开关，以及一次调用即可完成的会话引导。于 v0.49.0 引入。
72 个 MCP 工具	Guide、Memory、Agent Substrate、Agent Control Plane、Neural edges、Contexts、Tags、Files（R2）、Analyses（Memory Analysis）、Resources、Secrets、Sleep Maintenance、Usage、API-Key Bindings
多提供商支持	使用 OpenAI 或可自托管的服务（Ollama、vLLM——本地、私密、零成本）生成嵌入
面向团队	工作区、RBAC、上下文隔离、共享记忆
Web UI	Next.js 仪表板——上下文、搜索设置、成员管理
5 分钟完成设置	运行 ./setup.sh 即可完成

架构

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)

大模型知识库——5 层实现

Karpathy 的 大模型 Wiki 模式 描述了一种 5 层「动态知识库」，超越了传统 RAG。Kagura 在团队规模上实现了全部 5 层：

层	Kagura 实现	与 Karpathy 模式的区别
摄取	REST /api/v1/memory、MCP remember、R2 文件存储、资源令牌	+ 二进制数据块，+ 多租户
编译	以 MCP 作为编译 API——聊天 Agent 通过结构化工具调用（remember(summary, content, type, tags)）进行编译，另有睡眠维护用于批量整合	持续微型编译（而非批量重写 Wiki）——输出由架构强制规范
索引	三重索引：BM25（关键词）+ Qdrant（语义）+ 赫布图（关系）——全部自动维护	无需手动维护 index.md
查询	混合搜索 + AI 重排序 + explore 图遍历	超越 Markdown 搜索——支持语义和关系查询
增强	赫布学习——每次 recall() 都会强化共同检索到的记忆之间的连接。睡眠维护会定期进行整合。	后台图谱演进（零大模型成本），而非由大模型驱动的页面重写

累积提升循环：目前需要显式调用（用户 / Agent 在综合答案后调用 remember()）。为减少噪声，综合答案的自动写回有意设为可选。

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

Kagura 将精准搜索和探索发现分为两条独立路径，各自针对不同用途进行优化：

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() — 探索发现。遍历 Neural Memory 图，查找关键词搜索会遗漏的相关记忆。
• Hebbian learning — 每次 recall() 都会在后台增强共同检索到的记忆之间的边。无需显式训练——随着你使用系统，图会自然增长。

这种分离是有意为之：将图信号混入 recall 会降低精准度（基准测试已验证）。相反，每条路径都专注于自身最擅长的任务。

**数据隔离：**所有数据均按 workspace_id → context_id → user_id 过滤。记忆不会跨边界泄漏。使用单个 Qdrant 集合并通过载荷过滤。

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

**向量后端：**默认使用 Qdrant。单进程的可自托管 / CLI / 边缘部署可以改用嵌入式 LanceDB 后端——“Kagura Lite”（预览版），无需单独运行 Qdrant 服务（KAGURA_VECTOR_BACKEND=lance, cd backend && uv sync --locked --extra lite）。不适用于多工作进程 / SaaS（LanceDB 仅支持单写入器）。参见部署 → 嵌入式向量后端。

快速开始

系统要求

	最低配置	推荐配置
CPU	2 核	4+ 核
RAM	4 GB	8+ GB
磁盘	10 GB 可用空间	20+ GB 可用空间

前置条件

• Docker 和 Docker Compose
• 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

使用 Claude Code：

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 自动配置）：

设置	必填	说明
API_KEY_SECRET	是	用于 API 密钥加密的密钥（自动生成）
AUDIT_HMAC_KEY / AUDIT_PSEUDO_SALT	生产环境	审计日志 HMAC 密钥和擦除盐值（自动生成）
OPENAI_API_KEY	是*	用于嵌入的 OpenAI API 密钥
SELF_HOSTED_BASE_URL	否	自托管后端 URL（默认：http://localhost:11434）
EMBEDDING_PROVIDER	否	openai（默认）或 self_hosted
GOOGLE_CLIENT_ID/SECRET	否	Google OAuth2 登录（可选——也可使用密码登录）
GITHUB_CLIENT_ID/SECRET	否	GitHub OAuth2 登录（可选）

* 使用记忆功能需要设置 OPENAI_API_KEY，或运行自托管推理服务（例如 Ollama）。

管理 CLI

命令	用途
python3 -m src.cli.setup_env	生成密钥并配置 .env.local（在 Docker 启动前运行）
python3 -m src.cli.create_admin	创建管理员、工作区、API 密钥、.mcp.json，并设置嵌入功能
python3 -m src.cli.reset_password	重置密码和/或 MFA
python3 -m src.cli.delete_admin	删除管理员（以便重新创建）
python3 -m src.cli.transfer_context_creator	将一位用户创建的上下文转移给另一位用户（CLI 管理员 → OAuth 账户，参见 docs/deployment.md）

请从 backend/ 目录运行。Docker API 容器必须处于运行状态。

平台特定说明

• WSL（Windows）：安装 Docker Desktop for Windows 并启用 WSL 集成
• macOS：安装 Docker Desktop for Mac。brew install [email protected] 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），并为 API_KEY_SECRET、AUDIT_HMAC_KEY、AUDIT_PSEUDO_SALT 设置私有值（openssl rand -hex 32）——API 不会使用默认值或 .env.example 中的占位值启动
• 前端环境变量：将 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 / PROMAX — 自定义套餐显示名称（默认值：S/M/L/XL）

连接 MCP 客户端

支持 Claude Code、Claude Desktop、Claude Chat、ChatGPT、Gemini、Gemini CLI，以及任何 Streamable-HTTP MCP 客户端。

Claude Code（3 步）：

1. 启动服务并打开 http://localhost:3000/workspace/integrations/credentials?tab=api-keys 以创建 API 密钥
2. 将 .mcp.json.example 复制为 .mcp.json，并填入你的 API 密钥（在此处创建的密钥仅适用于其所在工作区）：

cp .mcp.json.example .mcp.json
# Edit .mcp.json — set the API key

.mcp.json.example 默认使用包含所有工具的 URL。将 "url" 设置为以下其中一个：

• 核心工具（默认）： http://localhost:8080/mcp
• 所有工具： http://localhost:8080/mcp?profile=full

OAuth 客户端（Claude.ai、Claude Desktop、ChatGPT、Gemini、Cursor、claude mcp add）使用相同的 /mcp URL，并连接到 Web UI 中选定的工作区；如果你属于多个工作区，使用 /mcp/w/{workspace_id} 可将此类连接器固定到一个工作区。

默认 URL 会列出核心记忆和上下文工具（具体集合见 Tool Profiles），而不列出 Sleep、分析、文件、边、密钥、资源和 Agent 控制平面工具——它们只是不在列表中。会话内的 describe_tools 会列出这些工具，而且大多数客户端只允许模型调用已列出的工具，因此需要这些工具的任务应使用下方的 URL 重新连接。如果你希望客户端一开始就能看到所有工具架构，请添加 ?profile=full（列表规模约为默认的 2.6 倍）。参见 工具配置。

3. 重启 Claude Code 并验证：

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/ 模板、kagura-memory Claude Code 插件（技能 + 工具防护钩子），以及 WSL2 网络说明：MCP 客户端设置

MCP 工具

14 个类别共 72 个工具：指南（guide，按需查看工具手册；describe_tools，查看 URL 未列出的工具）、记忆（remember / remember_batch / recall / explore …）、Agent 基础层（固定 + 定时触发的投递、确定性的 list / changes_since、一次调用完成的 bootstrap、状态、测量、反馈）、Agent 控制平面（预览版）、神经边、上下文、标签、文件（R2）、分析（记忆分析）、资源、密钥（零知识）、休眠维护、用量，以及 API 密钥绑定 — 每项均设有按角色划分的访问控制。

逐个工具的参考指南及所需角色：MCP 工具参考

Agent 的写入可以列出并撤销：每个会话使用 changes_since + rollback_session（无状态 MCP 客户端可以通过 _meta["ai.kagura/sessionId"] 或 Kagura-Session-Id 标头指定自己的会话），或者 — 对于没有会话 ID 的客户端 — 按时间范围查看自己的写入（by_me=true、since / until）；请参阅哪些客户端会获得会话 ID。

客户端无需列出全部 72 个工具：默认 URL 上方会列出 22 个核心工具（?profile=full 会列出所有工具），?tools=remember,recall 会精确列出你指定的工具，?add_tools=list_edges 则会列出核心工具和你指定的工具 — 请参阅工具配置。

REST API

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

• 记忆：记住、回忆、引用、遗忘、探索（/api/v1/memory/*）
• 上下文：CRUD、搜索设置（/api/v1/contexts/*）
• Agent（预览版）：注册表、上下文绑定和组合式引导（/api/v1/agents/*）
• 文件：由 R2 提供支持的预签名上传 / 下载（/api/v1/files/*，最高 100 MiB）；旧版 /api/v1/attachments/* 路由会返回 410 Gone
• 分析：记忆分析的预览 / 启动 / 读取 / 取消（/api/v1/analyses/*）
• 资源：外部事件摄取和资源检查（/api/v1/resources/*）
• 工作区：管理、成员、邀请（/api/v1/workspaces/*）
• 管理：用户、计划管理、神经配置（/api/v1/admin/*）
• 密钥：零知识密钥存储 — 仅存储密文，服务端永不解密（/api/v1/config/secrets/*）

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

身份验证

支持两种 OAuth2 提供商：

• Google OAuth2 — 可选。设置 GOOGLE_CLIENT_ID 和 GOOGLE_CLIENT_SECRET
• GitHub OAuth2 — 可选。设置 GITHUB_CLIENT_ID 和 GITHUB_CLIENT_SECRET

不同提供商下使用相同电子邮件地址的用户共用一个账户。无需任何 OAuth 提供商即可通过密码 + MFA 登录（请参阅快速入门）。现有账户也可以在个人资料中添加密码，然后使用已验证的电子邮件地址和该密码登录；请参阅部署 → 电子邮件 + 密码登录。

计划层级自定义

计划用于控制每个工作区的资源限额（上下文 / 记忆 / 每日 MCP 调用次数）。默认提供四个层级：S（free）、M（basic）、L（pro）和 XL（promax）。对于可自托管的单用户配置，请为工作区分配 XL（promax）计划 — 只有此层级可以创建资源、连接器和公开上下文（数值限额可通过环境变量覆盖；层级的功能集不可覆盖）。默认值、环境变量覆盖以及可选的 Stripe 自助账单：部署 → 计划层级

使用 Claude Code 进行开发

本项目旨在使用 Claude Code 和 Kagura Memory Cloud 本身进行开发 — 预配置的斜杠命令、安全钩子、子 Agent 和规则会从 .claude/ 自动加载。设置指南和完整工具参考：贡献 → 使用 Claude Code 进行开发

文档

API 参考 — 两个互补的入口：

• 概念介绍（markdown）：API 参考 — 身份验证、基础 URL、MCP 端点、请求/响应示例
• 端点参考（实时）：http://localhost:8080/redoc — 由 FastAPI 自动生成，始终与运行中的后端保持同步

概念与指南：

• 核心概念 — Workspace、Context、Memory、Neural Memory、MCP 工具
• MCP 客户端设置 — Claude Code / Desktop / Chat、ChatGPT、Gemini、Gemini CLI、插件与模板
• MCP 工具参考 — 全部 72 个工具及其所需角色
• 架构 — 系统设计与数据流
• 快速入门 — 详细的设置指南
• 分块指南 — 内存存储最佳实践
• 资源令牌指南 — 通过资源令牌摄取外部数据
• Neural Memory 评估 — 基准测试结果、架构决策
• 搜索质量基准测试 — 准确性测试、重排序、最佳实践
• 检索反馈与评估门控 — 反馈信号 + 禁止自我更新循环的策略（Agent Memory Substrate）
• 部署 — 使用 Caddy 反向代理进行生产环境部署
• 贡献指南 — 开发环境设置、代码风格、PR 工作流
• 安全 — 漏洞报告、安全设计
• Python SDK — KaguraClient（MCP），以及用于资源、文件、密钥、工作区和 Agent 引导的 REST 客户端，还有文档 FileIngestor
• 项目网站：www.kagura-ai.com — 概览、使用场景、快速入门路径

贡献

开发环境设置、代码风格和 PR 工作流请参阅 CONTRIBUTING.md。

许可证

Apache License 2.0