Zekra

功能

• 保留 / 检索 — 混合检索：密集向量 + 多语言 BM25，通过 RRF 融合， 再结合显著性加权、重排和 1 跳实体扩展。写入决策步骤 （ADD / UPDATE / INVALIDATE / NOOP）会更新相互矛盾的事实，而非重复添加。 内容不会被彻底删除：forget 会软失效，历史记录仍可查询。
• 多个大脑 — 每个项目或团队拥有独立命名空间，并通过服务器端强制执行的 Agent 授权和访问 令牌（cbt_…）进行管理。
• 知识图谱 — 从记忆中提取实体和类型化关系，并支持 traverse / neighbors / path / ontology 查询及图谱“主干”。
• 数据源 — 连接器（text、markdown、crawler、github、sql、webhook） 可拉取外部内容、将其分块，并通过相同的写入流程保留。 请参阅数据源。
• 与大脑对话 — 可调用工具的 Agent，会将大脑自身的 recall / search / graph / retain 用作工具，并通过引用和可审计的执行轨迹作答。
• 知识缺口、密钥保险库、活动日志 — 另提供一个 Web 控制台来统一管理。
• 分层存储 — Redis L1 工作记忆缓存、Postgres 热数据层、对象存储冷数据层。

快速开始

托管服务

在 app.zekra.dev 注册，创建一个大脑并生成令牌，然后 连接你的 Agent：

curl -fsSL https://app.zekra.dev/install.sh | sh     # installs the `zekra` CLI
zekra auth login --token <cbt_…>
zekra mcp:install claude-code                        # or claude-desktop | codex | gemini | cursor

CLI 位于 fadymondy/zekra-cli。

使用 Docker Compose 自托管

要求：Docker（含 Compose v2），以及约 6 GB 磁盘空间，用于存放嵌入和重排 模型。

git clone https://github.com/fadymondy/zekra.git && cd zekra
cp .env.selfhost.example .env.selfhost
# fill in POSTGRES_PASSWORD, AUTH_SECRET, ZEKRA_SECRETS_KEY and MFA_CHALLENGE_SECRET
# (generate each with: openssl rand -hex 32), and your email in ADMIN_EMAILS
docker compose -f docker-compose.selfhost.yml --env-file .env.selfhost up -d --build

打开 http://localhost:3020 并注册。该堆栈运行 Postgres 17（含 VectorChord）、一次性架构任务、Go API、Next.js 控制台，以及两个 CPU TEI 服务（嵌入和 重排），它们会在首次启动时下载模型。然后在 Admin → Tokens 下生成令牌，并运行 zekra auth login --url http://localhost:3020 --token cbt_…。

如需公开部署，请在前方设置 TLS 反向代理，并配置 APP_URL。所有设置均见 docs/self-hosting.md 和 DEPLOY.md。

MCP 工具

MCP 工具包括 memory_retain、memory_recall、memory_get、memory_forget、 memory_share、memory_edit、graph_*、memory_gaps、brain_*（list、grants、tokens、 chat）、secret_* 和 datasource_*。完整参考：MCP server · 合约：contracts/tools.md。

架构

  Claude Code · Codex · Cursor · your agents        web console · mobile · desktop · extension
          │ MCP (Streamable HTTP or stdio)                    │ REST / GraphQL / SSE
          └───────────────────────┬───────────────────────────┘
                 ┌────────────────▼─────────────────────────────────────┐
                 │ Go API (ToGO: plugins on a microkernel)               │
                 │  brain plugin: retain → write-decision (ADD/UPDATE/    │
                 │  INVALIDATE/NOOP) · recall: vectors + BM25 → RRF →    │
                 │  rerank → 1-hop graph · graph · data sources · chat   │
                 └──────┬──────────────────┬─────────────────┬───────────┘
                        │                  │                 │
           ┌────────────▼──────┐   ┌───────▼──────┐   ┌──────▼─────────┐
           │ Postgres + vchord │   │ TEI embed /  │   │ Redis L1 ·     │
           │ BM25 · partman    │   │ rerank       │   │ Cognee (opt.)  │
           └───────────────────┘   └──────────────┘   └────────────────┘

Zekra 是一款由插件构建的 ToGO 应用：

部分	位置	作用
brain	plugins/brain（模块 github.com/togo-framework/brain）	记忆器官：架构、保留/回忆、图谱、连接器、聊天、REST
brain-tei	plugins/brain-tei	通过 TEI 提供嵌入 + 重排序（Qwen3-Embedding-0.6B、bge-reranker-v2-m3）
brain-cognee	plugins/brain-cognee	实体/图谱提取引擎（Cognee）
cache-redis	plugins/cache-redis	L1 缓存
harness	cmd/api、cmd/migrate、internal/、web/	应用：API 服务、迁移、React 控制台
zekra-mcp	cmd/zekra-mcp	stdio MCP 服务——REST API 的轻量适配器
zekractl	cmd/zekractl	运维命令行：检查 DB、应用架构/BM25、BM25 冒烟测试、图谱镜像

设计：SPEC.md · 决策：contracts/internal/decisions.md · 部署：DEPLOY.md。

基于 ToGO 构建

Zekra 基于 ToGO（GitHub）构建。这是一个开源、API 优先的框架，适用于 Go + sqlc + Atlas + GraphQL/OpenAPI + Next.js，并提供 Laravel 风格的命令行。内核精简，其余功能均通过插件实现；Zekra 使用以下组件：

ToGO 组件	在 Zekra 中的作用
Kernel	配置、钩子/事件总线、插件注册表和服务启动
CLI	togo generate（sqlc → gqlgen → Atlas → OpenAPI）、togo serve、togo install
auth	登录、JWT 会话、角色和 API 令牌；MFA、通行密钥和 OAuth 由 auth 插件系列提供
db-postgres	brain 架构下的 Postgres 驱动程序
queue · cache · storage · mail	数据摄取任务、缓存、媒体和事务性电子邮件
插件模型	记忆器官本身以 ToGO 插件形式提供：brain、brain-tei、brain-cognee、cache-redis

想为自己的应用使用同样的基础？运行 go install github.com/togo-framework/cli@latest && togo new myapp， 然后阅读 ToGO 文档，并浏览插件市场。

阅读案例研究：Go 中的 MCP Server：Zekra 如何基于 ToGO 插件构建。

文档

完整文档见 **https://zekra.dev/en/docs**（源文件：[`docs/`](./docs)）：

• 简介和快速入门
• MCP server：工具参考和客户端配置
• CLI：zekra 命令和 Claude Code 插件
• REST API：端点、错误、事件、TypeScript 客户端
• 数据源 · 捕获钩子 · 安全 · 自托管

贡献

欢迎提交错误报告、文档和代码贡献。请先阅读 CONTRIBUTING.md，其中介绍了环境设置、规范和 DCO 签署。然后 查找 good first issue。 AI 编码 Agent 请从 AGENTS.md 开始。

翻译

Zekra 在 Hosted Weblate 上进行翻译，欢迎帮助我们将它翻译成你的语言： https://hosted.weblate.org/projects/zekra/。有关具体流程，请参阅 CONTRIBUTING.md。

社区

• Discord：与团队及其他用户交流
• GitHub Discussions：提问、分享想法和展示成果
• Issues：报告 Bug 和提出功能请求
• 安全问题报告：请参阅 SECURITY.md

请遵守行为准则。

赞助

Zekra 基于 ToGO 构建。ToGO 是一个开源的 Go + React 框架，为这一系列应用提供支持。支持 Zekra 的最佳方式是赞助 ToGO： 所有赞助款项都会用于框架及基于它构建的应用。

赞助 ToGO →

许可证

版权所有 (C) 2026 Fady Mondy。Zekra 是自由软件，依据 GNU Affero 通用公共许可证 v3.0（AGPL-3.0-only）授权。如果你将修改后的版本作为网络服务运行，必须向用户提供其源代码。第三方组件仍遵循各自的许可证。

**提供商业授权：**如需不受 AGPL 义务约束的许可证，请联系 [email protected]。

同一作者的更多开源项目

• TomatoPHP：60 多个适用于 Laravel 的开源 FilamentPHP 插件
• Laravilt：使用 Inertia 在 Vue 3 或 React 19 上渲染的 Laravel 管理面板
• ToGO：适用于 Go + React 应用的 Laravel 风格工作流，并提供插件市场

由 Fady Mondy 构建。