# super

**Repository Path**: lyuzb-apps/superbrain

## Basic Information

- **Project Name**: super
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-11
- **Last Updated**: 2026-07-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# superbrain

本地优先、可一键部署的个人记忆层——supermemory 的开源等价实现。给你的 AI 应用 /
Agent 一个**数据不出本机**的长期记忆：文档摄取、语义检索、事实抽取与矛盾消解、用户画像，
经 REST / MCP / 控制台三个消费面统一访问。

- **Memory ≠ RAG**：不只是检索切片，而是抽取事实级记忆、消解矛盾（ADD/SUPERSEDE/DUPLICATE）、维护版本链与用户画像。
- **即插即用**：MCP Server 挂载于 `/mcp`，Claude Code / Cursor 配置 token 即获记忆能力。
- **隐私优先**：`local-llm` 全离线 profile，运行态零外呼，数据完全留在本机。
- **中文一等公民**：提示词、控制台、语料全链路双语（中文默认）。

## 技术栈

后端 FastAPI + SQLAlchemy(async) + Postgres + Qdrant + BGE-M3 embedding + GLM（或本地
Ollama）；前端 React + Vite + TS + shadcn/ui + i18next；编排 Docker Compose。全开源 /
国内可用，单机可跑。

## 如何启动

### 前置要求

- **Docker** + **Docker Compose v2**（`docker compose` 子命令；不是旧的 `docker-compose`）。
- 内存 **≥ 16GB**（NFR-8 验收前提；默认模式 embedding 走 api 容器内 CPU 推理）。
- 默认模式需一个**智谱 GLM API key**（用于事实抽取/对话）；全离线模式则不需要外部 key。
- 可选：`make`（提供 `make up` / `make down` 快捷命令，会先校验 `.env`）。

### 默认模式（GLM API，最快上手）

1. 复制环境变量模板并填 key：

   ```bash
   cp .env.example .env
   ```

   编辑 `.env`，只需填一项 `OPENAI_API_KEY=<你的智谱 GLM key>`；
   `SUPERBRAIN_API_TOKEN` **留空**即可——首次启动会自动生成并回写到 `.env`（ADR-011）。
   除 `.env` 外无任何手工配置步骤（FR-35）。

2. 启动四服务（postgres / qdrant / api / web）：

   ```bash
   docker compose up -d --wait      # 或：make up（会先校验 .env 存在）
   ```

   `--wait` 会阻塞到所有容器 healthcheck 通过（冷启预算 ≤ 120s，模型已就位时）。

3. 启动后验证：

   ```bash
   curl http://localhost:8787/health         # 期望 200 / {"status":"ok"...}
   grep SUPERBRAIN_API_TOKEN .env             # 取首启自动生成的登录 token
   ```

   - **控制台**：http://localhost:8788 （用上面 `.env` 里的 `SUPERBRAIN_API_TOKEN` 登录）
   - **API**：http://localhost:8787 （健康检查 `GET /health`）
   - **MCP**：`http://localhost:8787/mcp` （Bearer token；Claude Code / Cursor 配置该 token 即获记忆能力）

### 停止 / 重启

```bash
docker compose down          # 停止并移除容器（数据卷保留，下次 up 数据还在）；或：make down
docker compose up -d --wait  # 重新启动
docker compose logs -f api   # 跟踪 api 日志排障
docker compose down -v       # ⚠️ 连同数据卷一起删除（清空全部记忆/文档，慎用）
```

### 全离线模式（local-llm，数据零出域）

```bash
# 1. 合并 .env.local-llm.example 的键进 .env（OPENAI_BASE_URL→ollama、EMBED_BACKEND=tei …）
# 2. 带 local-llm profile 启动（额外起 ollama / tei-embed / tei-rerank）
COMPOSE_PROFILES=local-llm docker compose up -d --wait
# 3. 首次拉模型（需联网；之后运行态零外呼）
docker compose exec ollama ollama pull glm-4-9b
```

详见 [docs/local-llm-degradation-matrix.md](docs/local-llm-degradation-matrix.md)（降级矩阵 +
零外呼说明）。切换只改 `.env`、零代码改动（FR-36）；**切换 embedding 后端后须
`POST /admin/reindex`** 重建向量索引（ADR-004）。

## 部署预期与最低规格

| 项 | 默认模式（GLM API） | local-llm 全离线 |
|----|--------------------|------------------|
| 首次安装时限 [ASSUMPTION，非门禁，FR-35] | ≤ 15 min | ≤ 60 min（含模型拉取） |
| 冷启动 healthcheck 预算（GATE-4，模型已就位） | ≤ 120s | ≤ 120s |
| 最低规格（NFR-8，验收前提） | 16GB 笔记本实测通过 | 建议更高内存（本地推理） |

> 时限为文档化预期（受网络/硬件影响），非 CI 门禁。冷启动 120s 预算以**模型权重已在卷中**为前置。

## 黄金路径验收（GATE-4）

```bash
make golden-path           # 默认模式：up→摄取→done→search→MCP recall→down/up 持久性
make golden-path-local     # local-llm 模式（须先切 .env）
```

见 [e2e/README.md](e2e/README.md)。

## 开发

```bash
make test                  # 后端 ruff+mypy+pytest + 前端 lint+typecheck+vitest
```

## 许可

开源（详见 LICENSE）。