内容
# 皮层
[](https://github.com/askmy-stack/cortex/actions/workflows/ci.yml)
[](LICENSE)
[](pyproject.toml)
[](mcp/)
**适用于人工智能原生公司的组织记忆操作系统。**
> 给组织中的每个 AI 代理提供与高级工程师相同的上下文，并在组织演变过程中保持更新。
**论点：** AI 工具是无状态的。组织不是。每个从零开始的代理都是 **记忆基础设施故障**，而不是模型故障。
<p align="center">
<img src="docs/assets/cortex-memory-fabric.gif" alt="Cortex memory fabric: Slack and GitHub events flow through Kafka extraction into Neo4j and Redis, then inject decision context into agents" width="920" />
</p>
<p align="center">
<em>从每个工具捕获决策 → 在知识图谱中构建结构 → 通过 MCP 在推理时主动注入上下文。</em>
</p>
| 3分钟速览 | 命令 |
|---|---|
| **实时演示** | [cortex-blush-theta.vercel.app](https://cortex-blush-theta.vercel.app) （仪表盘；设置 `CORTEX_API_ORIGIN` 在 Vercel 上进行 API 支持的搜索） |
| **本地运行** | `make demo` → [localhost:3000](http://localhost:3000) |
| **提问** | 工作区 `local-dev` → *为什么使用 CockroachDB 进行支付？* |
| **连接代理** | 添加下面的 MCP 模块 — `cortex_query`, `cortex_inject`, `cortex_remember` |
---
## 问题
目前每家运行 AI 的公司都存在相同的 silent 故障。
工具思考。代理行动。没有记忆。
- Cursor 会话不知道 Slack 线程中做出了什么决定
- 支持代理不知道上一季度销售的背景
- 新工程师的 Copilot 不知道为什么架构是这样构建的
- 代码审查机器人不知道哪些约束是架构性的还是临时的
每个 AI 交互都从零开始。每次都是如此。
这不是模型问题。每个主要实验室都解决了推理问题。
**这是内存基础设施问题。** 没有工具解决它。
---
## Cortex 功能
```
捕获决策 → 构建结构 → 注入上下文 → 代理智能行动
```
**Cortex 捕获决策，而不是文档。**
当您的团队决定将支付服务迁移到 CockroachDB 时，Cortex 会捕获：
```json
{
"type": "architectural_decision",
"decision": "迁移支付服务到 CockroachDB",
"replaces": "PostgreSQL",
"rationale": ["规模上限在 10M txn/day", "需要多区域复制"],
"made_by": ["priya@", "dan@"],
"triggered_by": "incident #247",
"affects": ["payments-service", "billing-service"],
"date": "2026-05-09",
"status": "active"
}
```
不是 Slack 消息。不是文档。是 **决策** — 结构化、链接、可查询。
**然后 Cortex 会主动注入它。**
当任何代理触及支付服务时，Cortex 会自动丰富其上下文：
```
"为什么支付使用 CockroachDB？"
→ Cortex 返回：触发它的事件、谁做出的决定、
讨论的权衡、迁移 PR、自那时起已知的边缘情况。
→ 代理正确回答。没有幻觉。没有考古。
```
---
## 关键能力
| 能力 | 描述 |
|---|---|
| **决策捕获** | 从 Slack、GitHub、Jira、Linear、会议中提取结构化决策 |
| **知识图谱** | Neo4j 图谱：决策 → 人 → 系统 → 异常 → 结果 |
| **主动注入** | 在代理行动之前将相关上下文推送给它们 — 而不是在它们提问之后 |
| **MCP 服务器** | 原生 MCP 端点 — 任何 Claude、Cursor 或 MCP 代理都可以通过一行配置获得内存 |
| **重要性评分** | 在摄入时过滤噪音 — 只有信号到达图谱 |
| **信任评分** | 每个内存节点的贝叶斯置信度 — 不好的输入不会破坏内存 |
| **矛盾检测** | 标记新事件与现有内存冲突时 — 没有静默覆盖 |
| **内存衰减** | 旧内存根据原则时间表压缩和存档 |
| **覆盖率评分** | 按领域估计完整性 — 代理知道内存何时稀疏 |
| **RBAC** | 图谱级访问控制 — 承包商看不到薪资决策 |
| **结果跟踪** | 将决策链接到实际指标 — 内存变得自我纠正 |
| **GDPR 删除** | 带有审计 trail 的级联删除；查询缓存每工作区无效 |
---
## 生产强化（启动就绪）
这些行为在预览或生产中运行 Cortex 时很重要：
| 问题 | 行为 |
|---|---|
| **GDPR 删除** | `POST /gdpr/erase` 提升工作区 Redis 缓存纪元 — 陈旧 PII 不能从 `/query` 中提供长达 60 秒 |
| **仪表盘代理** | `:3000` 上的 nginx 将 `/gdpr`（和 `/query`、`/inject` 等）转发到 API — 相同来源的演示有效 |
| **演示烟雾测试** | `scripts/demo.sh` 从 `.env` 获取并在设置 `CORTEX_DEMO_API_KEY` 或 `CORTEX_API_KEYS` 时发送 `Authorization` |
| **管道重试** | 暂时的 Neo4j 错误不会提交 Kafka 偏移量或进入 DLQ — 消息会重新传递 |
| **CMVK 快速失败** | `CORTEX_CMVK_BACKEND=openai\|ollama` 在工作器启动时验证凭证/可达性 |
```bash
# 预览/分段 .env 片段
CORTEX_API_KEYS=preview-key:admin;authenticated
CORTEX_DEMO_API_KEY=preview-key
CORTEX_CMVK_BACKEND=heuristic # 零成本本地演示；生产环境使用 openai + OPENAI_API_KEY
```
重新生成 README 动画：`python scripts/generate_readme_demo_gif.py` → `docs/assets/cortex-memory-fabric.gif`
---
## 部署
| 目标 | 指南 |
|------|--------|
| **$0 投资组合演示** （Cloudflare Pages + Render free + Aura + Upstash） | [docs/DEPLOY-FREE.md](docs/DEPLOY-FREE.md) |
| **生产分离** （Vercel 仪表盘 + Railway/Render API） | [docs/DEPLOY.md](docs/DEPLOY.md) |
部署后，验证端到端：`./scripts/verify_free_deploy.sh --api https://YOUR_API --pages https://YOUR_PAGES`
---
## 架构
```
┌──────────────────────────────────────────────────────────────┐
│ 捕获层 │
│ Slack · GitHub · Jira · Linear · 会议 · CI/CD │
│ 通过 Webhook 和 OAuth 连接器的实时事件流 │
└───────────────────────────────┬──────────────────────────────┘
│ Kafka
┌───────────────────────────────▼──────────────────────────────┐
│ 提取引擎 │
│ 决策提取器（GPT-4o 结构化输出） │
│ 实体解析器（spaCy NER → 规范组织实体） │
│ 重要性评分器（存储前过滤噪音） │
│ 事件分类器（决策/异常/理由/更新） │
└───────────────────────────────┬──────────────────────────────┘
│
┌───────────────────────────────▼──────────────────────────────┐
│ 内存结构 │
│ 事件 → TimescaleDB 发生了什么以及何时 │
│ 语义 → Qdrant 什么东西意味着什么 │
│ 结构 → Neo4j 关系 + 因果链 │
│ 程序 → Neo4j 事情如何完成 │
│ 热缓存 → Redis 代理实时检索 <50ms │
└───────────────────────────────┬──────────────────────────────┘
│
┌───────────────────────────────▼──────────────────────────────┐
│ 智能层 │
│ 矛盾检测器 · 衰减引擎 · 信任评分器 │
│ 覆盖率评分器 · 结果链接器 · RBAC 强制执行 │
└───────────────────────────────┬──────────────────────────────┘
│
┌───────────────────────────────▼──────────────────────────────┐
│ 上下文 API │
│ MCP 服务器 · REST API · Python SDK · TypeScript SDK │
│ cortex.query() · cortex.inject() · cortex.remember() │
└──────────────────────────────────────────────────────────────┘
```
---
## 快速入门
**最快路径 — 种子演示（推荐）：**
```bash
git clone https://github.com/askmy-stack/cortex
cd cortex
cp .env.example .env # 可选；本地演示的 compose 默认值生效
make demo # 基础设施 + 迁移 + 种子 + API + 工作器 + 仪表盘
open http://localhost:3000
```
在仪表盘上，打开 **Ask**，使用工作区 `local-dev`，并尝试：*为什么支付使用 CockroachDB？*
### 手动设置
```bash
# 核心基础设施（Kafka、Neo4j、Redis、Postgres）
docker compose up -d
# API + 管道工作器 + 仪表盘（类似生产环境，通过 Docker）
docker compose --profile api --profile frontend up -d --build
# 连接 Slack（可选 — 需要 .env 中的令牌）
python scripts/connect_slack.py --workspace your-workspace
```
**UI 开发（热重载）：** `cd frontend && npm run dev` → [http://localhost:5173](http://localhost:5173)
**Docker 仪表盘：** [http://localhost:3000](http://localhost:3000) （重建前端镜像后 UI 更改 — 见下面的注释）
### 一键演示（详情）
从存储库根目录开始，运行 Docker：
```bash
cp .env.example .env # 如果您依赖 compose 默认值，则可选
make demo # 或：bash scripts/demo.sh
```
这将启动 Kafka、Neo4j、Redis、Postgres，应用图谱迁移，写入两个演示 `Decision` 节点（CockroachDB 迁移故事 + Redis 会话缓存），启动 API、管道工作器和仪表盘，然后运行示例 `POST /query`。打开 [http://localhost:3000](http://localhost:3000) 并使用 **Ask** 工作区 `local-dev` 和问题 `为什么支付使用 CockroachDB？`。
**启用 API 认证？** 在 `.env` 中设置 `CORTEX_API_KEYS`（格式：`key:admin;authenticated`）和 `CORTEX_DEMO_API_KEY`（可选）以使 `make demo` 认证。
**生产环境 CMVK：** 默认 `CORTEX_CMVK_BACKEND=heuristic` 不需要 LLM。对于 `openai` 或 `ollama`，设置 `OPENAI_API_KEY` 或运行 Ollama — 如果后端配置不正确，管道工作器在启动时快速失败（避免静默隔离所有高风险写入）。
**仪表盘看起来过时？** UI 从 Docker 镜像在端口 **3000** 提供服务。 使用 `docker compose --profile api --profile frontend build frontend && docker compose --profile api --profile frontend up -d --force-recreate frontend` 重建，然后强制刷新浏览器（`Cmd+Shift+R`）。对于 UI 开发过程中的热重载，运行 `cd frontend && npm run dev` → [http://localhost:5173](http://localhost:5173)（开发服务器使用 **5173** 因此不会与 Docker 冲突）。
**录制 README 视频或 GIF：** 见 [docs/DEMO_RECORDING.md](docs/DEMO_RECORDING.md)。 **验证真实的 Webhook（Slack / GitHub / Jira）：** [docs/CONNECTOR_VALIDATION.md](docs/CONNECTOR_VALIDATION.md)。
### 上下文 API（REST）
| 方法 | 路径 | 目的 |
|--------|------|---------|
| `GET` | `/health` | 存活性和依赖检查（Neo4j、Redis） |
| `GET` | `/metrics` | Prometheus 暴露（请求 + 查询延迟直方图） |
设置 `OTEL_EXPORTER_OTLP_ENDPOINT` 以启用分布式跟踪（OpenTelemetry OTLP HTTP）。
| `POST` | `/query` | 决策搜索（Neo4j 全文 + 可选 Qdrant 合并，当 `CORTEX_SEMANTIC_ENABLED=true` 时） |
| `POST` | `/inject` | 代理的排名上下文 |
| `GET` | `/contradictions/pending` | 待处理矛盾审查项目（`workspace_id` 查询参数；`X-Cortex-Roles` 用于 RBAC） |
| `GET` | `/decisions/by-system/{system_id}` | 影响服务的最新决策 |
| `GET` | `/decisions/{id}/chain` | 替换 / 触发 lineage |
| `GET` | `/decisions/{id}/conflicts` | 共享系统上的矛盾预览 |
| `POST` | `/remember` | 提交显式内存 → Kafka → 提取器 → 图谱 |
| `POST` | `/gdpr/erase` | GDPR 擦除权 — 级联删除主题内存（`admin` / `gdpr_officer` / `legal`）；每工作区查询缓存无效 |
| `POST` | `/webhooks/slack`, `/github`, `/jira`, `/linear` | 连接器入口 → Kafka |
使用 `docker compose --profile api up` 构建 API 和管道工作器，或从存储库根目录运行 `uvicorn api.main:app --reload` 并使用 `.env` 中的服务。
**Python SDK：
```python
from sdk import CortexClient
client = CortexClient("http://localhost:8000")
print(client.query("为什么使用 CockroachDB?", workspace_id="local-dev"))
client.remember("我们使用 Redis 作为会话缓存。", workspace_id="local-dev")
```
**添加到任何 MCP 兼容的代理（Claude、Cursor） — `mcp/` 中的_stdio 服务器：**
```json
{
"mcpServers": {
"cortex": {
"command": "node",
"args": ["/path/to/Cortex/mcp/server.js"],
"env": { "CORTEX_API_URL": "http://localhost:8000" }
}
}
}
```
工具：`cortex_query`, `cortex_inject`, `cortex_remember`.
### 仪表盘
Web UI 面向工程师、产品经理和运营人员 — 不仅限于阅读 JSON 的开发人员。
| 区域 | 功能 |
|------|----------------|
| **首页** | 产品概述 + API 健康 |
| **Ask** | 组织内存上的自然语言搜索 |
| **内存图谱** | 关系图谱、时间线、决策血统 |
| **给代理** | 预览 `POST /inject` 将发送到 MCP 客户端的内容 |
| **审查** | 待处理矛盾队列 |
| **Cortex 指南** | 应用内助手，用通俗语言解释结果 |
---
## 演示
新工程师打开 Cursor。提问：
> *"为什么支付服务使用 CockroachDB 而不是 Postgres?"*
| 没有 Cortex | 有 Cortex |
|---|---|
| 代理猜测或说 *"我不知道"* | 返回事件 #247、决策所有者、权衡、迁移 PR、自那时起的边缘情况 |
| Slack 考古学、陈旧的 Confluence | 来自实时图谱的结构化 `DecisionEvent` |
| 每个会话从零开始 | MCP `cortex_inject` 在推理前推送上下文 |
完整上下文。~3 秒。没有考古学。
```mermaid
sequenceDiagram
participant Agent as Cursor / Claude
participant MCP as Cortex MCP
participant API as Context API
participant Graph as Neo4j + Redis
Agent->>MCP: cortex_query("CockroachDB payments")
MCP->>API: POST /query
API->>Graph: RBAC-filtered search + cache
Graph-->>API: decisions + lineage
API-->>MCP: ranked memory
MCP-->>Agent: incident, owners, rationale, systems
```
---
## 项目结构
```
cortex/
├── connectors/ # 工具连接器（Slack、GitHub、Jira、Linear）
│ ├── slack/
│ ├── github/
│ ├── jira/
│ └── linear/
├── extraction/ # 决策提取器、实体解析器、分类器
├── scoring/ # 重要性评分器、信任评分器、覆盖率评分器
├── graph/ # Neo4j 图谱、迁移、Cypher 查询
│ └── migrations/ # V001__initial_schema.cypher, 等
├── pipeline/ # Kafka 提取工作器（原始 → 图谱）
├── memory/ # 事件 → TimescaleDB 发生了什么以及何时
│ 语义 → Qdrant 什么东西意味着什么
│ 结构 → Neo4j 关系 + 因果链
│ 程序 → Neo4j 事情如何完成
│ 热缓存 → Redis 代理实时检索 <50ms
├── intelligence/ # 矛盾检测器、衰减引擎、结果链接器
├── api/ # FastAPI 应用程序
├── mcp/ # MCP 服务器（TypeScript）
├── sdk/ # Python 客户端（查询、注入、记住）
├── frontend/ # React 仪表盘
├── infrastructure/ # Terraform、Docker 配置
├── tests/
├── scripts/ # 设置、种子数据、实用工具
├── docs/ # 架构图、ADRs
├── CLAUDE.md # 代理操作说明
├── SESSIONS.md # 构建会话日志
├── DECISIONS.md # 决策日志 + 代理说明
├── MISTAKES.md # 错误和学习
└── ARCHITECTURE.md # 完整系统架构规范
```
---
## 技术栈
| 层 | 技术 |
|---|---|
| 事件流 | Apache Kafka |
| 决策提取 | GPT-4o 函数调用（生产）/ Ollama Gemma（开发） |
| 命名实体识别 + 实体解析 | spaCy + 自定义模型 |
| 知识图谱 | Neo4j 5 |
| 向量存储 | Qdrant |
| 时序数据库 | TimescaleDB |
| 缓存 | Redis |
| API | FastAPI + JWT |
| MCP 服务器 | TypeScript（MCP SDK） |
| 代理运行时 | LangGraph |
| 前端 | React + Vite（仪表盘：Ask、内存图谱、Cortex 指南） |
| 基础设施即代码 | Terraform + AWS ECS |
| 可观察性 | Prometheus + Grafana |
| 机器学习跟踪 | MLflow |
| 身份验证 | Auth0 + JWT + DID（代理身份） |
---
## 路线图
| 阶段 | 范围 | 状态 |
|---|---|---|
| 阶段 0 | 架构 + 文档 | ✅ 完成 |
| 阶段 1 | Kafka + Slack 连接器 + 决策提取器 | ✅ 核心已发布 |
| 阶段 2 | GitHub + Jira + Linear 连接器 + Neo4j 图谱 | ✅ 已发布（Webhook → Kafka → 工作器） |
| 阶段 3 | REST API (`/query`, `/inject`) + MCP + Python SDK | ✅ 已发布 |
| 阶段 4 | 重要性 + 信任评分 + 图谱 RBAC | ✅ 已发布 |
| 阶段 5 | 矛盾检测器 + 衰减引擎 | ✅ 已发布 |
| 阶段 6 | React 仪表盘（Ask、内存图谱、指南、代理注入） | ✅ 已发布 |
| 阶段 7 | 实时演示 URL + 演示视频 + 开源发布 | 🔄 进行中 |
| 阶段 8 | 结果跟踪 + 覆盖率评分 | ⏳ 发布后 |
| 阶段 9 | 启发式机器人（隐含知识） | ⏳ 发布后 |
| 阶段 10 | 跨组织联邦内存 | ⏳ v2 |
**CI:** GitHub Actions 在推送/拉取请求时运行 `pytest` + 种子干运行（`.github/workflows/ci.yml`）。
---
## 为什么存在
现有解决方案分为两类：
**内存系统** （Mem0、Zep、认知） — 架构深入，但跨工具捕获有限、单代理范围、无决策提取。
**企业搜索** （Glean、Notion AI、Dust） — 连接器深入，但仅限拉取、没有时间图、没有因果推理、没有决策捕获。
Cortex 是两个阵营之间的基础设施层。
组合 — 跨工具捕获 + 决策提取 + 时间因果图 + 主动 MCP 注入 + 重要性评分 + 组织范围 — 在任何开源或商业产品中都不存在。
---
## 研究基础
建立在：
- **MAGMA** （arXiv:2601.03236） — 四图内存架构（语义/时间/因果/实体）
- **Zep/Graphiti** （arXiv:2501.13956） — 时间边无效，延迟降低 90%
- **A-MEM** （NeurIPS 2025，arXiv:2502.12110） — Zettelkasten 动态内存链接
- **场论内存** （arXiv:2602.21220） — 热力学内存衰减（+116% F1）
- **SSGM 框架** （arXiv:2603.11768） — 内存稳定性和安全性治理
- **上下文工程** （arXiv:2603.09619） — 作为组织基础设施的上下文工程
---
## 许可证
Apache 2.0 — 使用、fork、构建。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器