内容
English · [Português (Brasil)](README.pt-BR.md)
---
# 🧠 智能客服图谱 v3.8.2
**开源的长期记忆（LTM）与认知宫殿，适用于 AI 代理、IDE 和开发者环境**
[](LICENSE)
[](pyproject.toml)
[](https://modelcontextprotocol.io/)
[](docker-compose.yml)
智能客服图谱是一款高性能、本地的认知记忆服务器，旨在解决大型语言模型（LLM）的“健忘症”和上下文窗口污染问题。与简单的检索增强生成（RAG）脚本不同，智能客服图谱作为一个双时间、自愈的记忆引擎，结合了关系型 SQL 持久化、向量搜索、分层上下文合成（缩放齿轮）和自主后台维护（管家循环）。
---
## 💡 什么是智能客服图谱？（适合初学者和资深开发者）
### 👶 简单解释（类比）
> 想象你雇佣了一位杰出的资深软件工程师，但他患有短期记忆丧失。每当你在 Cursor 或 Claude Desktop 中打开一个新的聊天窗口时，他都会忘记你的项目结构、编码标准和过去的架构决策。
>
> **智能客服图谱就是这位工程师的永久外部大脑。** 通过模型上下文协议（MCP）无缝连接，你的 AI 助手在毫秒级内自动查询、学习和更新这个大脑，而无需你再复制和粘贴上下文！
### 🧙♂️ 技术深入解析（适合工程师）
智能客服图谱是一个本地/VPS 守护进程，提供：
1. **双时间事实持久化**：存储语义事实和代码实体，带有明确的有效时间和事务时间跟踪。
2. **混合搜索 v4 引擎**：平衡密集向量嵌入（50%）、精确关键词签名通过 SQLite FTS5 BM25（25%）和图信号（25% 结合中心性和指数衰减 $W = W_0 \cdot e^{-\lambda t}$）。
3. **AST 感知顶点摄入**：将 Python、TypeScript、JS、Go、Rust、Java、C/C++ 文件解析为结构化 AST 节点，带有增量哈希（SHA-256）以跳过未修改的代码。
4. **自主自愈（管家循环）**：在后台线程中运行，以调和关系型 SQLite 表与向量集合、修剪孤儿嵌入和衰减不活动上下文。
---
## 🛡️ 关键架构优势（解决常见内存缺陷）
| 传统内存中的缺陷 | 智能客服图谱 v3.8.2 如何解决它 |
| :--- | :--- |
| **"错误抽屉"假阴性** | **动态作用域与回退**：如果本地相关性低于阈值，搜索会自动回退到参考翼（`all_wings=True`）。没有严格的锁定。 |
| **过时内存和矛盾** | **双时间失效和指数衰减**：`concierge_store_fact` 通过有效/事务时间戳使过时的事实失效，而管家通过 $W = W_0 \cdot e^{-\lambda t}$ 衰减不活动的节点。 |
| **双查询 I/O 延迟** | **亚 40ms 延迟（Colossus 基准）**：使用带有 SQLite WAL 模式和线程本地读取连接的 `SerializedWriteQueue` 实现超快的 P50（41ms）响应时间。 |
| **专有 SDK 锁定** | **原生 MCP 标准**：通过 Anthropic 的模型上下文协议（JSON-RPC/SSE）运行。零供应商锁定；与 Cursor、Claude Desktop、LangChain 或自定义脚本配合使用。 |
---
## ⚙️ 高级工程亮点
* ⚡ **轻量级 RAM 节省模式（`GRAFO_LIGHTWEIGHT_MODE=true`）**：通过绕过重向量模型并使用 SQLite FTS5 BM25 搜索，使智能客服图谱能够在低规格边缘硬件或 $4/mo VPS（512MB RAM）上运行。
* 🔍 **分层缩放齿轮（L0 ➔ L1 ➔ L2）**：将个别代码块（L0）合成到文件夹集群（L1）和项目范围的上下文指南针（L2），并具有选择性遗忘阈值。
* 🎯 **贝叶斯汤普森采样**：实时反馈环路（`concierge_feedback`），根据代理强化信号动态调整搜索评分权重。
* 🔐 **隐私翼隔离**：`PUBLIC`、`INTERNAL` 和 `RESTRICTED` 翼之间的结构分区，以防止跨租户上下文污染。
---
## 🔌 通过 MCP 实现同时连接多个客户端
由 Anthropic 的 **模型上下文协议（MCP）** 驱动，单个智能客服图谱服务器实例可以同时与您喜欢的所有工具通信：
```
┌───────────────────────────┐ ┌───────────────────────────┐
│ Cursor / Windsurf │ │ Claude Desktop │
└─────────────┬─────────────┘ └─────────────┬─────────────┘
│ │
│ JSON-RPC / SSE (MCP) │
└─────────────────┬────────────────┘
│
▼
┌─────────────────────────────┐
│ 🧠 智能客服图谱服务器 │
│ (本地 / VPS - 端口 8000) │
└─────────────────────────────┘
```
* 💻 **Cursor 和 Windsurf**：您的 IDE 代理在编写代码时动态搜索、回忆和提交项目内存。
* 💬 **Claude Desktop**：为您的桌面 AI 助手授予对您的存储库的即时宏观感知能力。
* 🤖 **自主代理和工作流**：通过 SSE 端点连接 n8n、LangChain、AutoGen 或自定义 Python 脚本。
---
## ⚡ 快速入门指南（3 分钟）
### 选项 1：通过 PyPI 安装（推荐大多数用户）
```bash
# 安装 Grafo Concierge 包和 CLI
pip install concierge-graph
# 随时卸载
pip install concierge-graph --upgrade # 更新
pip uninstall concierge-graph # 卸载
```
### 选项 2：从源代码本地设置（适用于开发者和贡献者）
1. **克隆和安装可编辑模式**：
```bash
git clone https://github.com/LuisinTheLegend/GrafoConcierge.git
cd GrafoConcierge
pip install -e .[dev]
```
2. **配置环境（`.env`）**：
```bash
cp .env.example .env
```
添加您的 Gemini 或 OpenAI 密钥：
```env
GRAFO_LLM_API_KEY=your_gemini_api_key_here
GRAFO_LLM_MODEL=gemini-2.0-flash
```
3. **启动 MCP 服务器**：
```bash
concierge-mcp
# 或：python main.py
```
---
### 选项 2：VPS 部署（直接 `pip` 或 `Docker`）🌐
您可以通过两种方式在任何 Linux VPS（Ubuntu/Debian）上托管智能客服图谱：
#### A) 直接安装（原生 `pip`）
```bash
# 1. 直接在您的 VPS 上安装
pip install concierge-graph
# 2. 设置您的环境变量（或创建 .env 文件）
export GRAFO_LLM_API_KEY="your_gemini_key"
export GRAFO_HOST="0.0.0.0"
export GRAFO_API_KEY="your_secure_vps_token"
# 3. 启动服务器
concierge-mcp
```
#### B) 容器化安装（Docker 🐳）
```bash
# 在 .env 中为远程安全设置 API 密钥
echo "GRAFO_API_KEY=your_secure_vps_token" >> .env
# 启动容器化服务器
docker compose up -d
```
---
## 💻 IDE 和 Claude Desktop 的一键配置
### 对于 Claude Desktop（`claude_desktop_config.json`）
将智能客服图谱添加到您的配置文件中：
```json
{
"mcpServers": {
"concierge-graph": {
"command": "python",
"args": ["-m", "interface.mcp_server"],
"cwd": "/path/to/GrafoConcierge",
"env": {
"GRAFO_LLM_API_KEY": "your_api_key_here"
}
}
}
}
```
### 对于远程 VPS / SSE 连接（Cursor / 自定义脚本）
在服务器运行时：
```json
{
"mcpServers": {
"concierge-graph": {
"url": "http://your-vps-ip:8000/sse",
"headers": {
"Authorization": "Bearer your_secure_remote_token"
}
}
}
}
```
---
## 🚀 性能基准（Colossus 协议）
在 **Colossus 协议**下针对 20,000 个代码节点进行测试：
| 指标 | 结果（20,000 个节点） |
| --- | --- |
| **搜索延迟（P50）** | 41.69 毫秒 |
| **搜索延迟（P99）** | 112.75 毫秒 |
| **可扩展性因素** | 0.93x（保留线性性能） |
| **摄入吞吐量（SQLite）** | 约 536 节点/秒 |
| **摄入吞吐量（ChromaDB）** | 约 914 向量/秒 |
| **后台维护（管家）** | 在约 11 秒内协调 20,000 个孤儿向量 |
---
## 🛠️ 混合搜索 v4 公式
相关性分数通过组合三个不同的信号来计算：
$$\text{分数} = (0.50 \times \text{向量相似性}) + (0.25 \times \text{归一化 FTS5 BM25}) + (0.25 \times \max(\text{最近度}, \text{中心度}))$$
1. **向量相似性（50%）**：使用密集嵌入捕获深层概念意义。
2. **FTS5 BM25（25%）**：函数名称、类和符号的精确令牌签名。
3. **图信号（25%）**：
- **中心度**：节点的相对连接性（归一化入度）。
- **最近度**：基于时间的指数衰减，确保历史上下文优雅地老化：
$$W = W_0 \cdot e^{-\lambda t}$$
---
## 🔌 核心 MCP 工具参考
* **`concierge_mine`**：摄入目录，分割代码（AST），提取标签，并生成 L0/L1/L2 摘要。
* **`concierge_search`**：跨索引项目运行完整的混合搜索 v4 管道。
* **`concierge_wakeup`**：在会话启动时通过返回上下文指南针、参考翼和最近提交来恢复代理意识。
* **`concierge_resume`**：检索项目上下文的宏观摘要（适用于系统提示符注入）。
* **`concierge_load`**：按需惰性加载完整节点内容、边和依赖项。
* **`concierge_commit`**：将审计的架构更改注册到认知账本。
* **`concierge_store_fact`**：记录用户偏好和架构规则，并具有双时间失效。
---
## 🛠️ 全局 CLI 子命令参考（`concierge`）
运行 `pip install concierge-graph` 后，通过 `pyproject.toml` 安装两个全局终端命令：
1. **`concierge-mcp`**：启动 FastMCP 服务器守护进程。
2. **`concierge`**：支持以下子命令的多功能 CLI 实用程序：
```bash
# 1. 注册新工作区/项目
concierge register --name my-project --wing backend --privacy PUBLIC
# 2. 将代码库目录摄入内存图
concierge mine --path /path/to/codebase --name my-project
# 3. 跨索引内存执行混合搜索 v4
concierge search --query "authentication middleware" --project my-project
# 4. 重新激活代理意识（指南针 + 翼 + 提交）
concierge wakeup --project my-project
# 5. 检索上下文指南针宏摘要
concierge resume --project my-project
# 6. 将审计的架构提交到账本
concierge commit --project <uuid> --phase build --technical_changes "Added Auth JWT"
# 7. 按需惰性加载单个节点
concierge load --node_id 42
# 8. 显示系统健康状况、计数和数据库状态
concierge status
# 9. 列出本地数据库中的所有已注册项目
concierge projects
# 10. 删除项目和所有关联的关系和向量记录
concierge delete --project my-project
```
---
## 🧪 测试套件和健康诊断
运行所有单元和压力测试：
```bash
python -m pytest
```
运行完整的内存诊断：
```bash
python -m tests.check_brain
```
---
## 📄 许可证
在 MIT 许可证下分发。有关详细信息，请参见 `LICENSE`。
