内容
# kube-memory
**DevOps 智能代理的组织记忆。**
[kube-memory.buildlab.in](https://kube-memory.buildlab.in/) 为 AI 编码助手和 CI 管道提供了一个持久、可查询的基础设施历史记录——事件、修复、部署和结果——这样下一次故障发生时， agent 可以从已有经验中学习，而不是从空白开始。
每个事件都遵循一个简单的循环：检测症状、诊断原因、应用治疗、记录结果。随着时间的推移，您的集群会建立起机构记忆，这种记忆可以在会话重置、工程师交接和重复中断后仍然存在。
---
## 已部署的 URL
| 界面 | URL | 用途 |
|---------|-----|---------|
| **仪表盘（客户端）** | [https://kube-memory.buildlab.in/](https://kube-memory.buildlab.in/) | 注册、连接集成、管理 API 密钥、IDE 设置 |
| **API 服务器** | [https://kube.buildlab.in/](https://kube.buildlab.in/) | MCP (`POST /mcp`)、REST (`/ingest`、`/memory/query`、`/status`)、健康检查 |
**IDE 配置的 MCP 端点：** `https://kube.buildlab.in/mcp`
```json
{
"mcpServers": {
"kube-memory": {
"url": "https://kube.buildlab.in/mcp",
"headers": {
"Authorization": "Bearer km_xxxxxxxxxxxxxxxxx"
}
}
}
}
```
从 [仪表盘](https://kube-memory.buildlab.in/) → **API 密钥** 获取 `km_*` 密钥。
---
## kube-memory 提供什么
### 智能代理的语义记忆
通过 [Cognee](https://www.cognee.ai/) 提供的语义搜索功能存储和检索 DevOps 事件。在处理警报或部署之前，智能代理会询问 *"我们以前是否遇到过这种情况，解决方法是什么？"* 在解决事件后，结果将被写入，以便下次查询。
| 工具 | 功能 |
|------|----------------|
| `memory_remember` | 将事件、修复、部署结果和运行手册持久化到工作区记忆中 |
| `memory_recall` | 对过去事件的语义搜索——OOM 杀死、部署失败、配置漂移 |
| `memory_forget` | 删除过时或敏感的条目（管理员） |
| `predict_risk` | 根据类似的过去故障为计划的部署评估风险 |
### MCP 原生 - 一个端点，所有集成
将 Cursor、VS Code、Claude Desktop 或任何 MCP 兼容的客户端连接到 `https://kube.buildlab.in/mcp`。一个 `km_*` API 密钥解锁 **29 个工具**，涵盖记忆、平台状态和实时基础设施读取——按工作区划分，通过仪表盘中的连接器配置控制。
### 工作区仪表盘
在 [kube-memory.buildlab.in](https://kube-memory.buildlab.in/) 管理所有内容：
1. **注册** - 邮箱/密码或 GitHub OAuth
2. **集成** - 连接 Kubernetes、GitHub、Slack、PagerDuty、Prometheus 或 ArgoCD（测试 → 保存 → 启用）
3. **API 密钥** - 为 IDE 和自动化颁发 `km_*` 密钥（需要 ≥1 个集成）
4. **IDE 设置** - 从 API 密钥页面复制 MCP 代码段
每个工作区都是隔离的：它自己的 Cognee 记忆数据集、加密的连接器凭证和按角色划分的 API 密钥（`reader`、`admin`）。
### 用于自动化的 REST API
IDE 中使用的同一个记忆图在 `https://kube.buildlab.in` 处可用于管道和 cron 作业——摄入结构化事件、运行语义查询并检查工作区状态。完整参考：[server/API_DOC.md](./server/API_DOC.md)。
---
## 如何开始
1. 打开仪表盘 → [https://kube-memory.buildlab.in/](https://kube-memory.buildlab.in/)
2. 完成设置流程：**集成 → API 密钥 → IDE**
3. 将 kube-memory 添加到您的 MCP 配置中 - 端点 `https://kube.buildlab.in/mcp`，从仪表盘获取密钥
4. 让您的智能代理回忆过去的事件、拉取 pod 日志、检查 ArgoCD 同步状态或评估部署风险
详细演练： [usage.md](./usage.md)
---
## MCP 工具目录
工具通过 `POST https://kube.buildlab.in/mcp` 使用您的工作区 API 密钥调用。可用性取决于您启用的集成。
### 记忆
| 工具 | 访问权限 | 描述 |
|------|--------|-------------|
| `kube_memory_status` | reader+ | 列出启用的集成和工作区提示 |
| `memory_remember` | admin | 存储事件、部署或修复 |
| `memory_recall` | reader+ | 过去事件的语义搜索 |
| `memory_forget` | admin | 删除过时或敏感的记忆 |
| `predict_risk` | reader+ | 根据召回相似性评估部署风险 |
### Kubernetes
| 工具 | 访问权限 | 描述 |
|------|--------|-------------|
| `k8s_pod_logs` | reader+ | 从连接的集群读取 pod 日志 |
| `k8s_get_events` | reader+ | 列出集群或命名空间事件 |
### GitHub
| 工具 | 访问权限 | 描述 |
|------|--------|-------------|
| `github_get_authenticated_user` | reader+ | PAT 用户身份 |
| `github_list_repositories` | reader+ | 列出仓库 |
| `github_list_recent_commits` | reader+ | 账户活动中的最新提交 |
| `github_list_issues` | reader+ | 列出仓库的问题 |
| `github_list_pull_requests` | reader+ | 列出拉取请求 |
| `github_list_commits` | reader+ | 列出分支或路径上的提交 |
| `github_get_pull_request` | reader+ | 获取单个拉取请求 |
### Slack
| 工具 | 访问权限 | 描述 |
|------|--------|-------------|
| `slack_get_history` | reader+ | 获取最近的频道消息 |
| `slack_list_channels` | reader+ | 列出 bot 可以访问的频道 |
| `slack_post_message` | admin | 向频道发送消息 |
### PagerDuty
| 工具 | 访问权限 | 描述 |
|------|--------|-------------|
| `pagerduty_list_incidents` | reader+ | 按状态/服务/时间列出事件 |
| `pagerduty_get_incident` | reader+ | 获取事件详情 |
| `pagerduty_list_services` | reader+ | 列出服务 |
| `pagerduty_get_incident_log_entries` | reader+ | 获取事件时间线日志条目 |
| `pagerduty_list_incident_notes` | reader+ | 列出事件备注 |
| `pagerduty_list_oncalls` | reader+ | 列出当前正在值班的人员 |
| `pagerduty_list_users` | reader+ | 列出 PagerDuty 用户 |
### Prometheus
| 工具 | 访问权限 | 描述 |
|------|--------|-------------|
| `prometheus_query` | reader+ | PromQL 即时查询 |
| `prometheus_query_range` | reader+ | PromQL 时间窗口范围查询 |
| `prometheus_list_alerts` | reader+ | 列出触发的警报 |
| `prometheus_list_targets` | reader+ | 列出抓取目标和健康状态 |
| `prometheus_list_rules` | reader+ | 列出警报和记录规则 |
| `prometheus_list_alertmanagers` | reader+ | 列出活跃的 Alertmanager 端点 |
| `prometheus_list_labels` | reader+ | 列出指标标签名称 |
| `prometheus_list_label_values` | reader+ | 列出指标标签值 |
### ArgoCD
| 工具 | 访问权限 | 描述 |
|------|--------|-------------|
| `argocd_list_applications` | reader+ | 列出 GitOps 应用程序 |
| `argocd_get_application` | reader+ | 应用程序同步/健康状态 |
| `argocd_get_app_history` | reader+ | 部署修订历史 |
| `argocd_list_app_events` | reader+ | 同步和部署事件时间线 |
| `argocd_get_app_resource_tree` | reader+ | 应用程序的实时资源树 |
| `argocd_list_projects` | reader+ | 列出 ArgoCD 项目 |
| `argocd_list_repositories` | reader+ | 列出连接的 Git 仓库 |
| `argocd_sync_application` | admin | 触发同步 |
| `argocd_rollback_application` | admin | 回滚到以前的修订 |
---
## 架构
```mermaid
flowchart TB
subgraph Surfaces["操作员和智能代理界面"]
direction LR
IDE["IDE 智能代理\nCursor · VS Code · Claude Desktop"]
CI["CI / cron / 脚本"]
WEB["网页仪表盘\nkube-memory.buildlab.in"]
end
subgraph Gateway["kube-memory 服务器\nkube.buildlab.in"]
direction TB
AUTH["身份验证层\nJWT 会话 · GitHub OAuth · km_* API 密钥"]
MCP["MCP 网关\nPOST /mcp · JSON-RPC 2.0\n工具/列表 · 工具/调用"]
REST["REST 工作区 API\n/ingest · /memory/query · /status"]
CONN["连接器保险库\nAES-加密的每个工作区密钥\n测试 · 启用 · 禁用"]
CRON["定时作业\nCognee 在数据集上改进（）"]
end
subgraph Tools["MCP 工具平面 - 25 个工具"]
direction TB
subgraph MemTools["语义记忆"]
direction LR
T_MR["memory_remember"]
T_MRC["memory_recall"]
T_MF["memory_forget"]
T_PR["predict_risk"]
end
subgraph InfraTools["实时基础设施读取"]
direction TB
subgraph K8s["Kubernetes 连接器"]
direction LR
T_KPL["k8s_pod_logs"]
T_KGE["k8s_get_events"]
end
subgraph GH["GitHub 连接器"]
direction LR
T_GHI["github_list_issues"]
T_GHPR["github_list_prs"]
T_GHC["github_list_commits"]
T_GHGP["github_get_pr"]
end
subgraph Slack["Slack 连接器"]
direction LR
T_SH["slack_get_history"]
T_SLC["slack_list_channels"]
T_SPM["slack_post_message"]
end
subgraph PD["PagerDuty 连接器"]
direction LR
T_PDL["pagerduty_list_incidents"]
T_PDG["pagerduty_get_incident"]
T_PDS["pagerduty_list_services"]
T_PDLE["pagerduty_get_incident_log_entries"]
T_PDN["pagerduty_list_incident_notes"]
T_PDO["pagerduty_list_oncalls"]
T_PDU["pagerduty_list_users"]
end
subgraph Prom["Prometheus 连接器"]
direction LR
T_PQ["prometheus_query"]
T_PQR["prometheus_query_range"]
T_PA["prometheus_list_alerts"]
T_PT["prometheus_list_targets"]
T_PR["prometheus_list_rules"]
T_PAM["prometheus_list_alertmanagers"]
T_PL["prometheus_list_labels"]
T_PLV["prometheus_list_label_values"]
end
subgraph Argo["ArgoCD 连接器"]
direction LR
T_AL["argocd_list_apps"]
T_AG["argocd_get_app"]
T_AH["argocd_get_history"]
T_AE["argocd_list_app_events"]
T_ART["argocd_get_app_resource_tree"]
T_AP["argocd_list_projects"]
T_ARP["argocd_list_repositories"]
T_AS["argocd_sync"]
T_AR["argocd_rollback"]
end
end
end
subgraph Data["数据和外部系统"]
direction LR
COGNEE[("Cognee Cloud\n语义记忆图\n每个工作区数据集")]
MONGO[("MongoDB\n用户 · 工作区\nAPI 密钥 · 连接器")]
K8S_EXT["Kubernetes API"]
GH_EXT["GitHub API"]
SL_EXT["Slack API"]
PD_EXT["PagerDuty API"]
PR_EXT["Prometheus"]
AR_EXT["ArgoCD"]
end
subgraph Loop["事件循环"]
direction LR
L1["1 · 检测\n警报 · 部署失败 · OOM"]
L2["2 · 诊断\n召回 · 日志 · 指标 · 事件"]
L3["3 · 治疗\n同步 · 回滚 · 补丁 · 发布"]
L4["4 · 记录\n记录结果以备下次查询"]
L1 --> L2 --> L3 --> L4
L4 -.->|"馈送召回"| L2
end
IDE -->|"Bearer km_*"| MCP
CI -->|"Bearer km_*"| REST
CI -->|"Bearer km_*"| MCP
WEB -->|"JWT"| AUTH
AUTH --> MCP
AUTH --> REST
AUTH --> CONN
MCP --> MemTools
MCP --> InfraTools
REST --> MemTools
CONN --> K8s
CONN --> GH
CONN --> Slack
CONN --> PD
CONN --> Prom
CONN --> Argo
MemTools --> COGNEE
T_MR --> COGNEE
T_MRC --> COGNEE
T_MF --> COGNEE
T_PR --> COGNEE
K8s --> K8S_EXT
GH --> GH_EXT
Slack --> SL_EXT
PD --> PD_EXT
Prom --> PR_EXT
Argo --> AR_EXT
AUTH --> MONGO
CONN --> MONGO
CRON --> COGNEE
Loop -.->|"智能代理工作流"| IDE
```
### 凭证和界面
| 界面 | URL | 凭证 | 使用者 |
|---------|-----|------------|---------|
| 仪表盘 | [kube-memory.buildlab.in](https://kube-memory.buildlab.in/) | JWT（会话） | 登录后的浏览器 |
| MCP | [kube.buildlab.in/mcp](https://kube.buildlab.in/mcp) | `km_*` API 密钥 | Cursor、VS Code、Claude Desktop |
| REST | [kube.buildlab.in](https://kube.buildlab.in/) | `km_*` API 密钥 | CI 管道、脚本、自动化 |
API 密钥按角色划分：**reader** 工具为只读；**admin** 可以写入记忆、发布到 Slack、同步/回滚 ArgoCD 和忘记条目。
---
## 文档
| 文档 | 描述 |
|----------|-------------|
| [usage.md](./usage.md) | 设置流程、集成和 MCP 使用 |
| [docs/setup.md](./docs/setup.md) | 本地开发设置 |
| [server/API_DOC.md](./server/API_DOC.md) | 完整的 REST 和 MCP API 参考 |
| [server/.env.example](./server/.env.example) | 服务器配置 |
| [PLAN.md](./PLAN.md) | 产品愿景和路线图 |
---
## 许可证
请参阅存储库许可证文件。
