cortex

一个为家庭或团队打造的自托管大脑：一个仪表面板，人们可以在其中相互聊天，也可以与一个能读取他们共享笔记的智能代理聊天——使用你自己的模型，在你自己的机器上运行。

状态：alpha。 API 和配置界面仍在稳定中；预计在次要版本之间会有破坏性变更。索引和检查点格式是可丢弃的缓存——删除 .cortex/ 会丢失对话，但绝不会丢失笔记。

pip install cortxai
cortex setup                 # wizard: brain dir, model endpoint, admin account
cortex serve --host 0.0.0.0  # dashboard on :8642

或者运行 bash install.sh（自动检测 pipx/uv/venv），或者在一次性执行 cortex setup /brain（docker-compose.yml 中有文档说明）后运行 docker compose up。

它不做什么： cortex 不托管模型——你需要自带端点：Ollama、vLLM、LM Studio、LiteLLM 代理、OpenRouter 或 Anthropic API。向量搜索是进程内的精确余弦计算，适合个人和团队规模的大脑，但不适合数百万个分块。Vault 编辑采用最后写入者胜出策略，并带有冲突检测（409 错误和横幅提示），而非 git 级别的合并。日历连接器目前还不展开重复规则。

仪表面板

• 聊天 — 与智能代理的私有线程。它在回答之前会先搜索，流式输出其工具调用（⚙ search_brain … ✓ 33ms），并按路径引用文件；点击引用会在仓库视图中打开该文件。

• 频道 — 大脑上成员之间的对等聊天。提及 @cortex，智能代理就会在频道内回答，只读取共享仓库——绝不会读取任何人的个人仓库。

• 仓库 — 共享和个人仓库，在浏览器中编辑，支持 Obsidian 风格的渲染：[[wikilinks]]、![[embeds]]、> [!note] 标注、frontmatter、可写回的任务复选框、#tags。Ctrl-S 保存；并发编辑会显示冲突横幅，而不是静默覆盖。

• 导入 — 通过 zip 上传、git URL 或服务器路径导入现有的 Obsidian 仓库。.obsidian/、.git/ 和非仓库文件类型会被跳过。

• 管理 — 账户（admin / member）、索引统计。

账户采用用户名 + 密码（scrypt），会话使用 HttpOnly cookie。每个用户都能看到共享仓库、自己的仓库以及连接器来源——搜索、grep 和智能代理按请求进行作用域限定，在查询内部过滤，而不是在查询后裁剪。

Related MCP server: claudecode-mcp

智能代理栈

LangGraph 的 ReAct 智能代理基于 LangChain 聊天模型，对话状态存储在每线程的 AsyncSqliteSaver 检查点中：

providers:
  local:
    kind: openai                    # Ollama, vLLM, LM Studio — one wire
    base_url: "http://localhost:11434/v1"
    chat_model: qwen3
    embed_model: nomic-embed-text
  router:
    kind: openrouter                # cloud aggregator, OpenAI wire
    api_key_env: OPENROUTER_API_KEY
    chat_model: anthropic/claude-sonnet-5
  claude:
    kind: anthropic                 # direct Anthropic Messages API
    api_key_env: ANTHROPIC_API_KEY
    chat_model: claude-sonnet-5
roles:
  chat: router
  embed: local

LiteLLM 代理是 kind: litellm，带有其 base_url——其路由和回退策略保留在代理中，因此 cortex 不携带 LiteLLM SDK。端点根据网络事实分类：私有地址、环回地址、CGNAT 和 Tailscale 地址是可信的；任何公共地址都会收到一个明确的警告，提示你的笔记将离开网络。

检索是混合式的：SQLite FTS5 和向量余弦分别排序，通过倒数排名融合（reciprocal rank fusion）合并，并受新近度影响——这是来自 Cerebras 知识库 的设计。当分块模式或嵌入模型发生变化时，索引会从头重建，因为静默混合向量空间就是数据损坏。没有嵌入端点意味着全文搜索会明确说明这一点，而不是伪造向量分数。

四种扩展方式

一个损坏的扩展会被报告并隔离，绝不会导致致命错误。注册不等于授权：一个触及敏感内容的工具会在可调用对象内部保留自己的检查。

从仪表板管理它们。 仅限管理员的 扩展 面板列出每个插件、技能、连接器和 MCP 服务器，并显示其提供的内容、加载错误（如果有）以及一个启用开关，该开关绝不会编辑你的源文件。你可以在浏览器中编写插件或连接器：它在保存前就会被加载，因此无法导入的代码会被拒绝，并显示加载器自己的消息，而不是静默破坏下一轮；成功保存会重建智能体，因此新工具无需重启即可生效。连接器有设置框和“立即运行”按钮；MCP 服务器有表单。在 cortex.yaml 中定义的服务器以只读方式显示——文件仍然是其声明内容的拥有者。

保存插件或连接器会以 cortex 用户身份在服务器上运行该代码。这与配置 stdio MCP 服务器的信任级别相同，这也是该面板仅限管理员的原因。从终端，cortex ext list、cortex ext disable plugin <name> 和 cortex ext delete 可以执行相同的管理操作，而无需浏览器。

Cortex 也是一个 MCP 服务器 —— claude mcp add home-brain -- cortex mcp --brain ~/brain 为 Claude Code、Cursor 或 Hermes 提供相同的工具注册表，作用域为盒子所有者。

大脑的布局

~/brain/
├── cortex.yaml        # providers, roles, mcp servers, connectors
├── vaults/shared/     # everyone's notes
├── vaults/<user>/     # each user's private vault
├── sources/           # connector output
├── skills/ plugins/ connectors/
└── .cortex/           # index, checkpoints, usage.jsonl — disposable cache

通过复制文件夹来备份它。家庭大脑、公司大脑、俱乐部大脑：三个文件夹，三个 cortex serve 进程。

可观测性

每次模型和工具调用都会将 JSONL 追加到 .cortex/usage.jsonl，当端点报告 prompt_tokens/completion_tokens 时，会包含这些数据——缺失的计数保持缺失，而不是变成零，这正是 preflight 进行校准所期望的。遥测绝不会导致调用失败。

开发

uv venv --python 3.12 && uv pip install -e '.[dev]'
.venv/bin/pytest                    # 102 tests
.venv/bin/ruff check src tests
cd web && npm install && npm run dev   # SPA dev server, proxies to :8642

前端契约在 docs/product-spec.md 中；发布版本见 RELEASING.md。

文档： unchained-labs.github.io/cortex · 品牌： Unchained-Labs/branding · 许可证： MIT