Cortex

Cortex

通过 MCP、CLI 和 REST 提供可自托管的家庭实验室日志智能分析，并使用 SQLite/FTS。

它收集日志和运维证据，将其存储在启用 FTS5 搜索的 SQLite 中，并通过 CLI、REST、MCP 和内置浏览器工作区提供统一的智能分析层。

Cortex 最初是一个 syslog 接收器。如今，它涵盖网络日志、Docker、托管文件、OpenTelemetry 日志、指标和追踪、主机心跳、设备群清单、Shell 和 Agent 活动，以及 Claude、Codex、Gemini CLI 和 Antigravity 的对话记录。它会将这些来源关联起来，生成时间线、事件和有证据支撑的拓扑图，同时不让图成为第二个事实来源。

概览

领域	Cortex 提供的功能
数据接入	UDP/TCP syslog、OTLP/HTTP 日志、指标和追踪、Docker 日志和事件、托管文件跟踪、主机心跳、AI 对话记录、Shell 历史记录、Agent 命令记录和设备群清单
存储	WAL 模式的 SQLite、FTS5 全文搜索、有界元数据、保留策略、存储预算、维护任务、检查点，以及 63 个顺序执行的架构迁移
调查	搜索、筛选、上下文、时间线、模式、异常对比、跨来源关联、重复错误特征、确定性事件包和图谱说明
设备群智能分析	SSH 和 API 清单收集器、主机状态、服务拓扑、容器和路由关系、经过脱敏的证据，以及可重建的图谱投影
AI 运维	Claude、Codex、Gemini CLI 和 Antigravity 会话索引；提取各提供方公开的技能、MCP 和钩子事件；事件聚类；以及受保护的本地大模型评估
接口	原生 CLI、一个按操作分派的 MCP 工具、经过身份验证的 REST API、MCP 提示词和资源、MCP Apps 搜索小组件，以及内置调查工作区
运维	设置和修复、诊断、Compose 控制、备份、完整性检查、WAL 检查点、清理、更新工作流、Agent 和运行状况端点

重要

Cortex 面向可信的家庭实验室或小型私有设备群。它不是集群日志仓库、通用 SIEM，也不适合在公共互联网上暴露未经过身份验证的管理界面。

目录

• 快速开始
• Cortex 的构建方式
• 数据接入
• 调查与智能分析
• 设备群清单与图谱
• AI 会话智能分析
• 告警与通知
• 接口
• 配置
• 身份验证与信任边界
• 存储与维护
• 部署与分发
• 运维
• 开发与验证
• 文档
• 当前边界
• 许可证

快速开始

安装 CLI

首选的引导式流程是：

npx skills add dinglebear-ai/cortex --skill install-cortex

启动一个新的 Agent 任务并调用 $install-cortex。它会选择服务端或仅客户端角色，将任务委派给标准安装/设置引擎，配置身份验证、网络和存储，并验证客户端的实时连接。

npm 启动器仍然是本地 CLI 和 stdio MCP 使用场景中最快的手动方式：

npx -y @dinglebear/cortex --help
npx -y @dinglebear/cortex mcp

使用以下命令永久安装：

npm install --global @dinglebear/cortex
cortex --version

启动器需要 Node.js 18 或更高版本。它会下载经过校验和验证的原生发布二进制文件，适用于 Linux x64、Linux ARM64、macOS ARM64 或 Windows x64。

使用当前稳定版 Rust 工具链从源代码构建：

git clone https://github.com/dinglebear-ai/cortex.git
cd cortex
mise install       # optional, but pins the repository tools
just build
./.cache/cargo/debug/cortex --version

启动本地服务

完整守护进程会启动 UDP 和 TCP syslog 接收器以及共享 HTTP 服务。请使用独立的 MCP 和 REST 令牌：

mkdir -p "$HOME/.cortex/data"
export CORTEX_DB_PATH="$HOME/.cortex/data/cortex.db"
export CORTEX_TOKEN="$(openssl rand -hex 32)"
export CORTEX_API_TOKEN="$(openssl rand -hex 32)"

cortex serve mcp

默认值：

• Syslog：UDP 和 TCP 使用 0.0.0.0:1514
• HTTP：127.0.0.1:3100
• MCP：http://127.0.0.1:3100/mcp
• REST：http://127.0.0.1:3100/api/*
• 调查工作区：http://127.0.0.1:3100/app

在另一个终端中验证：

curl -fsS http://127.0.0.1:3100/health
logger -n 127.0.0.1 -P 1514 --tcp "cortex quickstart from $(hostname)"

export CORTEX_API_TOKEN="the-same-api-token"
cortex tail --limit 10

对于受管理的本地部署，cortex setup repair 会创建或修复 Cortex 主目录、Compose 资源和数据路径，并补齐缺失的 64 字符 MCP 和 REST 令牌，而不会替换现有令牌值。

连接 MCP 客户端

仅查询的 stdio 模式会读取已配置的本地数据库，且不会启动网络监听器：

{
  "mcpServers": {
    "cortex": {
      "command": "npx",
      "args": ["-y", "cortex-rmcp", "mcp"],
      "env": {
        "CORTEX_DB_PATH": "/absolute/path/to/cortex.db"
      }
    }
  }
}

Streamable HTTP 模式会连接到持久运行的守护进程：

{
  "mcpServers": {
    "cortex": {
      "url": "http://127.0.0.1:3100/mcp",
      "headers": {
        "Authorization": "Bearer your-cortex-token"
      }
    }
  }
}

一个实用的首次调用是：

{"action":"status"}

然后，使用更广泛的分析操作之前，可通过 tail、errors、search、timeline 或 context 缩小调查范围。

Cortex 的构建方式

Cortex 是一个具备多种运行模式的 Rust 二进制文件。同一个应用和服务层为 CLI、REST 处理程序和 MCP 处理程序提供支持，因此验证、限制、身份解析、脱敏和业务规则并不专属于某一种传输方式。

                         INGESTION

  Syslog UDP/TCP       OTLP signals       Docker agent / pull
  Managed file tails  Heartbeats         Claude / Codex / Gemini / Antigravity
  Shell history       Agent commands     Fleet inventory
          \               |                    /
           \              |                   /
            +---- bounded parsing and enrichment ----+
                              |
                    scrub, normalize, batch
                              |
                    SQLite WAL + FTS5
                              |
             +----------------+----------------+
             |                                 |
    authoritative records             derived accelerators
    logs, heartbeats,                 rollups, signatures,
    inventory, sessions              graph projections
             |                                 |
             +----------------+----------------+
                              |
                     shared service layer
                              |
          CLI       REST       MCP       Web workspace

守护进程通过协作式取消来监管接收器和后台服务。关闭时会排空 HTTP 请求，给维护任务 10 秒完成，之后执行中止并等待；给摄取流程 5 秒进行刷新，然后尝试执行 WAL 检查点。已经运行的阻塞式 SQLite 调用无法由 Tokio 取消。

后台服务包括：

• 保留策略和存储预算的执行
• WAL 和 FTS 维护
• Docker 摄取监管
• 文件尾随监管
• 错误签名扫描
• 通知评估、分发和摘要调度
• 清单刷新和回填
• 图投影刷新
• AI 会话和时间线汇总
• 数据库优化和维护作业

繁重的分析读取和维护作业采用独立的并发控制，避免某项高开销调查耗尽摄取路径的资源。

数据摄取

所有类似日志的来源都会规范化为相同的持久化日志模型，在确保安全的情况下进行丰富处理，按配置进行清理，并通过有界批处理路径写入。

通过 UDP 和 TCP 使用 Syslog

Cortex 在同一个可配置端口上监听 UDP 和 TCP Syslog。它会解析常见的 RFC 3164 和 RFC 5424 格式，保留原始帧，记录发送方身份，规范化严重性和设施，并丰富已知的应用程序格式。

相关默认值：

• 绑定地址：0.0.0.0:1514
• 最大消息大小：8 KiB
• 最大并发 TCP 连接数：512
• TCP 空闲超时：300 秒
• 写入批次：100 条记录或 500 毫秒
• 写入队列容量：10,000 条记录

Syslog 没有应用层身份验证。若监听器可从可信网络之外访问，请使用网络控制和 CORTEX_ALLOWED_SOURCE_CIDRS 限制发送方。

内置丰富处理可识别 AdGuard、Authelia、Docker 生命周期事件、fail2ban、Linux 内核和 OOM 事件、SWAG、反向代理日志，以及主机本地 Cortex Docker Agent 元数据中的有用信号。来源门控可限制丰富处理对未经过身份验证的 syslog 正文中标记的信任。

OpenTelemetry 接入

Cortex 会在共享 HTTP 监听器上接受 protobuf OTLP/HTTP 导出请求。日志使用 POST /v1/logs，请求体上限为 4 MiB，并流经常规写入器。指标使用 POST /v1/metrics，追踪使用 POST /v1/traces；二者的请求体上限均为 8 MiB，并使用专用存储。指标请求最多允许 5,000 个数据点，并且还会限制规范化后的负载大小。

当前 OTLP 支持范围有意保持精简：

• 支持通过 HTTP/protobuf 传输日志、追踪和指标。
• 尚未实现 OTLP/gRPC。

这三个 OTLP 端点都使用 CORTEX_TOKEN 进行身份验证——与保护 POST /mcp 的静态 MCP bearer 令牌相同；在已部署的主机上，该令牌从 ~/.cortex/.env 读取。它不是 CORTEX_API_TOKEN（REST /api/*），也不是 CORTEX_API_ADMIN_TOKEN。回环和可信网关策略会跳过此检查。仅使用 OAuth 且未设置静态令牌的部署会直接拒绝 OTLP，因为机器导出器没有 OAuth 流程。因此，除非设置了 CORTEX_TOKEN，否则启动时会拒绝非回环的仅 OAuth OTLP 暴露配置。

Docker 日志和事件

Cortex 支持两种 Docker 采集方式：

1. 主机本地 Agent，多主机环境下的首选方式。主机本地的 cortex agent 会读取本地 Docker socket，将日志和生命周期事件转换为有界记录，并转发到服务端，而无需更改 Docker 的守护进程日志驱动程序。
2. 中央拉取兼容模式，一种可选的服务端采集器，可用于显式配置的 Docker Engine 或 docker-socket-proxy HTTP 端点。它会记录每个容器的检查点，并通过有界指数退避机制重新连接。

中央拉取默认处于禁用状态。CORTEX_DOCKER_HOSTS 简写会将主机扩展为不安全的 http://host:2375 端点，因此只应在严格受控的专用网络上使用。主机文件支持显式指定基础 URL 和更安全的端点配置。

受管文件尾随

受管文件尾随源会持久化在注册表中，并由守护进程负责监管。可通过 CLI、REST 或 file_tails MCP 管理操作添加、移除、列出和检查源。

路径策略会拒绝不安全的目标，包括配置根目录之外的路径、符号链接逃逸、非普通文件和敏感挂载。容器部署会显式提供只读文件尾随根目录，而非整个主机文件系统。

主机心跳

主机 Agent 可以向 POST /v1/heartbeats 发送有界 JSON 快照。心跳包含主机状态信息，例如负载、内存、磁盘、网络、进程和容器摘要。这些信息为 host_state、fleet_state 和 correlate_state 提供支持。

心跳请求体上限为 256 KiB。心跳数据采用较短的运维保留期限，与主要日志保留策略分开。

AI 转录记录

Cortex 会索引本地和转发的转录数据，来源包括：

• ~/.claude/projects 下的 Claude Code 项目
• ~/.codex/sessions 和 ~/.codex/worktrees 下的 Codex 会话和工作树
• ~/.gemini/tmp 下的 Gemini CLI 聊天数据
• ~/.gemini/antigravity/brain/<session>/.system_generated/logs/transcript.jsonl 下的 Antigravity 桌面版脱敏转录投影
• ~/.gemini/antigravity-cli/brain/<session>/.system_generated/logs/transcript.jsonl 下的 Antigravity CLI 脱敏转录投影

Antigravity 适配器只读取上述范围有限的脱敏 JSONL 投影，不会扫描对话数据库或其他 brain 产物。扫描器支持增量检查点、解析错误记录、有界数据块、宽泛路径拒绝，以及对已更改文件的安全恢复。它会提取规范化的转录行，以及专用的技能、MCP 工具调用和钩子事件（前提是提供方架构中包含相应通道），并如实报告不支持的通道。

卫星 Agent 可以将已解析的记录发送到 POST /v1/ai-transcripts，这样转录采集就不必依赖于 AI 客户端所在主机上的数据库。

Shell 和 Agent 活动

卫星 Agent 可以向共享服务器转发其他运行证据：

• POST /v1/agent-commands 用于去重后的 Agent 命令暂存记录
• POST /v1/shell-history 用于解析后的 Bash、Zsh 扩展历史记录和 Atuin 记录

这些记录采用与 Cortex 其余部分相同的存储和关联模型，因此，Agent 变更或 Shell 命令会与随后发生的服务故障并列显示。

设备群清单

清单收集会根据本地文件、SSH 探测、Docker 端点和可选服务 API，构建经过脱敏的设备群快照，然后将安全的关系投影到调查图谱中。

调查和情报

Cortex 提供范围受限的工作流，而不是原始 SQL 控制台。

搜索和上下文

• FTS5 全文搜索，支持按主机、应用、严重性、来源、项目、会话和时间筛选
• 仅针对索引字段的结构化筛选检索
• 最新记录尾部和单行检索，附带原始帧证据
• 某个日志 ID 或时间戳附近的上下文
• 主机、应用和源 IP 清单
• 使用事件时间戳和接收时间戳测量时钟偏差

时间和容量分析

• 分桶时间线
• 接收速率和队列压力状态
• 近重复消息模式聚类
• 与基线相比的近期异常检测
• 并排比较时间范围
• 静默主机和静默数据流检测
• 数据库、存储和运行时统计信息

关联

• 围绕某个时间戳进行跨主机关联
• 将 AI 会话锚点与基础设施日志关联
• 在构建时间线前，通过实体图谱解析主题
• 跨日志、心跳和清单进行主机状态关联
• 使用 FTS5 查找历史事件相似项
• 附带范围受限证据的确定性事件上下文包

重复错误

可选的后台扫描器会将重复出现的错误签名归组为持久化记录。运维人员可以检查尚未处理的签名、确认签名、撤销确认，并将签名与日志和图谱证据关联。

错误检测默认处于禁用状态。启用后，它会扫描范围受限的批次，不会为较低严重性的重复错误触发告警，并且只有达到配置的严重性下限时才会发送通知。

设备群清单和图谱

清单收集器

原生清单子系统可以收集并规范化以下来源的证据：

• 本地和远程 Compose、反向代理及 AdGuard Home 配置
• 本地进程、存储、项目和原始配置清单
• 到远程设备群主机的 SSH 会话
• 本地和远程 Docker 端点
• Tailscale
• UniFi
• Unraid
• 媒体栈服务及相关 API

SSH 收集采用严格的主机密钥验证、有限并发、超时和重试退避策略。敏感字段会在持久化前进行脱敏。

缓存默认位于 ~/.cortex/inventory，其中包括：

• normalized/homelab.json：类型化的规范设备群快照
• collection-state.json：收集器健康状态、耗时和警告状态
• raw/<run-id>/...：原始但经过脱敏的辅助材料

map 操作会读取规范化缓存，不会触发收集，也不会返回原始配置正文或包含凭据的 URL。

派生调查图谱

该图谱连接以下规范实体：

• 主机和源身份
• 逻辑服务和具体服务实例
• 应用和容器
• 域名、路由和端点
• AI 项目和会话
• 错误特征和运维发现

关系包含置信度、信任度、原因代码、时间戳和有界证据引用。该图谱支持实体解析、邻域查询、拓扑问题、证据查找和解释路径。

该图谱是可重建的投影。原始日志、心跳、资产记录、错误特征和 AI 会话数据仍是权威数据源。重建投影时会使用暂存表，并执行一次短暂的串行化切换，同时记录水位线和指标；若刷新失败，则保留明确的降级状态。

AI 会话智能

Cortex 将 AI 转录内容视为运维证据，而不只是聊天存档。

确定性会话分析

共享服务层可以：

• 按项目列出并搜索会话
• 按五小时使用时段衡量活动
• 汇总项目上下文
• 列出观察到的工具和项目
• 检测挫折或滥用信号
• 将这些信号归类为带评分的事件
• 将 AI 活动与非 AI 基础设施日志关联起来
• 提取技能调用
• 提取 MCP 服务和工具调用事件
• 提取钩子配置和运行时事件
• 构建以技能、MCP 和钩子为首的调查资料包

确定性查询和事件工作流可通过 CLI、REST 和 MCP 使用。

受控的本地评估

基于 LLM 的评估刻意限制为仅在本地运行。它们通过 cortex assess 执行，不会作为 MCP 操作或 REST 路由公开，因为它们会生成本地提供方子进程。

CORTEX_LLM 为所有 LLM 操作选择提供方和可选模型：包括技能、MCP、钩子和滥用评估，以及试运行审计元数据。设置 CORTEX_LLM=codex（默认值，使用 Codex app-server）或 CORTEX_LLM=gemini（Gemini CLI）。要全局固定模型，请使用 CORTEX_LLM=codex/gpt-5.5 或 CORTEX_LLM=gemini/gemini-3.1-flash-lite-preview。如果 CORTEX_LLM 中指定了显式模型，则优先于 --model；否则，现有标志可为单次调用选择模型。选择器为空或不受支持时会失败，不会回退到其他提供方。

该选择器也适用于受管理的 ~/.cortex/.env；进程环境变量优先。配置加载后会保留设置。

旧变量 CORTEX_CODEX_MODEL 和 CORTEX_HEADLESS_GEMINI_MODEL 会被忽略。命令和认证主目录的覆盖项仍属于安装设置，而非提供方选择器。--no-llm 无需提供方配置或凭据。

共享 LLM 运行器会强制执行：

• 全局熔断开关
• 全局和按操作划分的并发限制
• 按分钟和按小时的速率限制
• 按操作划分的熔断器和冷却时间
• 调用超时
• 提示词和输出字节上限
• 默认禁用的显式后台增强开关
• 成功、失败、超时和策略拒绝的持久化审计记录

默认防护值允许同时执行 1 次调用；每项操作每分钟 3 次、每小时 30 次；超时时间为 120 秒；提示词上限为 1 MiB，输出上限为 256 KiB。

默认启用提示词清理。技能、MCP 和钩子事件的提取会在经过清理的转录文本持久化之前进行，因此无需存储原始提示词即可保留结构化运维信号。

警报和通知

通知为可选功能，默认禁用。启用后，Cortex 使用 Apprise 作为发送桥接，并使用持久化的 SQLite 待发箱进行重试、去重和死信处理。

内置评估器涵盖：

• OOM 终止
• 容器以非零状态退出
• fail2ban 封禁
• Authelia MFA 失败
• 磁盘填满和存储护栏压力
• 采集队列压力
• 采集完全静默
• 心跳静默
• 此前活跃的持续流静默

通知子系统包括：

• 可配置的评估器运行周期
• 按规则启用或禁用及设置阈值
• 去重时间窗口
• 按故障期间划分的静默键
• 有界重试和死信状态
• 最近触发历史记录
• 测试通知
• 定时每日摘要

默认情况下，持续流静默跟踪涵盖 UDP/TCP syslog、Agent Docker、Docker 流和事件记录，以及受管文件尾随。转录和 shell 历史等零星来源会有意排除。

接口

CLI

运行 cortex --help 和各命令的 --help，查看生成的命令树。

分组	用途
search、filter、tail	日志检索
hosts、apps、entity、graph	发现和拓扑
analysis、correlate、state、stats、timeline	调查和分析
sessions、assess	AI 会话查询和本地受保护的评估
alerts	错误特征、确认和通知历史
ingest、heartbeat	采集器、Agent、文件尾随、清单和心跳
serve、mcp	完整守护进程和仅查询的 stdio MCP 模式
doctor、status、db、compose	诊断和维护
setup、update、config、completions	生命周期和运维工具

示例：

cortex search "oom killer" --host devhost --since 1h
cortex filter --severity err --since 6h
cortex timeline --since 24h
cortex sessions search "migration failure"
cortex graph explain --help
cortex alerts errors list
cortex ingest inventory refresh --json
cortex ingest filetail list
cortex status
cortex doctor

CLI 支持直接/本地运行和 HTTP 运行。REST 后端模式是常规远程路径，使用 CORTEX_URL 和 CORTEX_API_TOKEN。

MCP

Cortex 提供一个名为 cortex 的 MCP 工具。必填的 action 字段从唯一权威的 Rust 注册表中选择一个操作。通过机械生成的当前数量已发布在实时覆盖率清单中。

当前范围划分如下：

• 53 个需要 cortex:read 的读取操作
• 6 个需要 cortex:admin 的管理操作：artifact_evidence_record、ack_error、unack_error、file_tails、notifications_test 和 llm_invocations
• 1 个信息类操作 help；挂载身份验证时需要经过身份验证的上下文，但不需要读取/管理范围

完整 MCP 操作目录

领域	操作
日志检索	search、filter、tail、errors、get、context
发现和运行状况	hosts、apps、source_ips、status、stats、ingest_rate、silent_hosts、clock_skew
分析和关联	timeline、patterns、anomalies、compare、correlate、topic_correlate、similar_incidents、recurring_error_comparison、incident_context
集群和拓扑	map、host_state、fleet_state、correlate_state、graph、compose_status、compose_doctor
AI 会话和限定范围的证据	sessions、search_sessions、session_investigate、evidence_scope、abuse、abuse_incidents、abuse_investigate、ai_correlate、usage_blocks、project_context、list_ai_tools、list_ai_projects
AI 运维事件	skill_events、skill_incidents、skill_investigate、mcp_events、mcp_incidents、mcp_investigate、hook_events、hook_incidents、hook_investigate
错误和管理	unaddressed_errors、ack_error、unack_error、notifications_recent、notifications_test、file_tails、llm_invocations、artifact_evidence_record
参考	help

运行时架构包含各操作的标志、默认值、示例、相对成本元数据和验证规则。参数参考请参阅 docs/mcp/SCHEMA.md。

MCP 提示词

Cortex 提供 12 个可复用的基础设施提示词：

• infra.incident-triage
• infra.host-health
• infra.service-outage
• infra.security-auth-review
• infra.noise-reduction
• infra.agent-change-correlation
• infra.docker-container-regression
• infra.network-dns-failure
• infra.storage-pressure
• infra.auth-bruteforce
• infra.syslog-forwarding-gap
• infra.after-deploy-check

参数和输出预期请参阅 docs/mcp/PROMPTS.md。

MCP 资源和 UI

MCP 服务提供：

URI	用途
cortex://schema/mcp-tool	动态 JSON 架构，用于按操作分发的工具
cortex://schema/prompt-output	结构化事件风格提示词输出的架构
ui://cortex/query-widget	独立的 MCP Apps 搜索小组件

查询小组件属于渐进式增强。支持 UI 的 MCP 宿主可以渲染它；普通 MCP 客户端则会继续收到常规文本和结构化 JSON 结果。

REST

经过身份验证的 JSON 路由位于共享 HTTP 监听器下的 /api/*。这些路由涵盖与 MCP 相同的主要查询领域，并增加了用于会话检查点、解析错误、数据库完整性任务、备份、检查点和清理的操作员工作流。

版本化调查 API 位于 /api/v1/* 下，为内置浏览器工作区提供 Ask Cortex 以及图实体、邻域、说明和证据端点。

REST 需要 CORTEX_API_TOKEN。特权维护和文件尾部读取工作流也可能需要 CORTEX_API_ADMIN_TOKEN。

路由和响应参考请参阅 docs/api.md。

浏览器调查工作区

守护进程在 /app 和 /app/investigate 提供内置工作区。它包含：

• 运行时和架构状态
• 服务器集群和数据摄取摘要
• Ask Cortex 调查请求
• 交互式 Cytoscape 图画布
• 证据检查
• 最近日志时间线

该应用嵌入 Rust 二进制文件中，无外部运行时依赖，采用严格的内容安全策略，并且仅在内存中保存输入的 REST bearer token。当前 UI 将自身定位为调查预览，而非通用的完整仪表板。

Claude Code 插件

.claude-plugin/plugin.json 将 Cortex 打包为 Claude Code 插件。它声明了恰好三个界面以及配置：

键	指向
mcpServers	plugins/cortex/mcp.json — 使用 ${user_config.server_url}/mcp 的 HTTP 传输，并带有 Bearer ${user_config.api_token} 标头
skills	plugins/cortex/skills/ — 12 个技能
userConfig	服务端与客户端模式、server_url、api_token、身份验证模式和 OAuth 字段、syslog/MCP 绑定主机和端口、保留和存储预算、Docker 数据摄取以及服务器集群主机

这 12 个技能分别是 cortex、frustration-assessment、hook-friction-assessment、incidents、logs、mcp-friction-assessment、report、searching-sessions、skill-improvement-assessment、topology、troubleshoot 和 version-check。

该插件不注册任何 Claude Code 生命周期钩子——没有 hooks 键，也没有 hooks.json。设置需要显式执行：安装、升级或重新配置后，运行 cortex setup pluginhook（或使用 plugins/cortex/scripts/plugin-setup.sh 适配器）。just validate-plugin 和 scripts/validate-marketplace.sh 会断言 hooks 键始终不存在，而 cargo xtask check-version-sync 会断言清单中没有顶层 version。

设置生命周期请参阅 docs/plugin/HOOKS.md，清单参考请参阅 docs/plugin/PLUGINS.md。

健康检查端点

• GET /health：为容器和代理提供精简的、未经身份验证的存活状态响应
• GET /health/full：详细的健康状况和数据摄取可观测性；挂载的身份验证需要 CORTEX_TOKEN（仅使用 OAuth 不足以通过验证）。显式环回和可信网关策略会绕过此检查。

配置

macOS 心跳 Agent 快速入门

从已登录的桌面会话中：

cortex setup heartbeatagent install
cortex setup heartbeatagent check

请先设置 CORTEX_HEARTBEAT_TARGET 和摄取凭据。 CORTEX_API_TOKEN 仅可用于查询，不能用于 Agent 摄取身份验证。有关功能、路径、 登录语义、迁移、恢复、移除和交付证明，请参阅权威的 macOS 心跳 Agent 运维契约。

Cortex 按以下顺序加载配置，后加载的层级优先：

1. 内置默认值
2. 当前工作目录中的部分 config.toml
3. 受管理的 $CORTEX_HOME/.env 文件，通常为 ~/.cortex/.env
4. 进程环境变量

重要默认值

设置	默认值
Syslog 绑定地址	0.0.0.0:1514，UDP 和 TCP
HTTP 绑定地址	127.0.0.1:3100
数据库路径	/data/cortex.db，除非由设置或环境变量覆盖
SQLite 连接池大小	8 个连接
SQLite 页面缓存预算	总计 128 MiB
SQLite mmap 目标	256 MiB
高负载读取并发数	1
WAL 检查点阈值	256 MiB
日志保留期	90 天
逻辑数据库上限	1,024 MiB
恢复阈值	900 MiB；上限大幅提高时会自动调整
清理间隔	60 秒
通知	已禁用
重复错误扫描器	已禁用
集中式 Docker 拉取	已禁用
提示词清理	已启用
后台大模型增强	已禁用

常用环境变量包括：

变量	用途
CORTEX_HOME	受管理的配置和运维主目录
CORTEX_DB_PATH	SQLite 数据库路径
CORTEX_RECEIVER_HOST、CORTEX_RECEIVER_PORT	Syslog 监听器
CORTEX_ALLOWED_SOURCE_CIDRS	可选的 Syslog 发送方允许列表
CORTEX_HOST、CORTEX_PORT	共享 HTTP 监听器
CORTEX_TOKEN	MCP、OTLP、心跳和转发使用的静态令牌 bearer token
CORTEX_API_TOKEN	REST bearer token
CORTEX_API_ADMIN_TOKEN	必要时使用的额外 REST 管理员令牌
CORTEX_AUTH_MODE	静态令牌或 OAuth 身份验证模式
CORTEX_PUBLIC_URL	用于 OAuth 和暴露验证的公共 URL
CORTEX_ALLOWED_HOSTS、CORTEX_ALLOWED_ORIGINS	Host 标头和 CORS 策略
CORTEX_RETENTION_DAYS	日志保留期
CORTEX_MAX_DB_SIZE_MB	逻辑数据库存储预算
CORTEX_MIN_FREE_DISK_MB	可选的外部可用空间写入保护
CORTEX_FILE_TAIL_ALLOWED_ROOTS	受管理的文件尾读根目录允许列表
CORTEX_DOCKER_INGEST_ENABLED	启用集中式 Docker 拉取兼容模式
CORTEX_SCRUB_PROMPTS	尽力清除 AI 提示词中的凭据
CORTEX_NOTIFICATIONS_ENABLED	启用通知服务
CORTEX_LLM	共享的提供商/模型选择器：codex[/MODEL] 或 gemini[/MODEL]；默认值为 codex
CORTEX_LLM_ENABLED	本地评估全局紧急关闭开关
RUST_LOG	跟踪过滤器

完整参考和验证规则请参阅 docs/CONFIG.md。

身份验证与信任边界

Cortex 有意区分传输凭据和功能权限。

MCP

• CORTEX_TOKEN 用于验证静态令牌 HTTP MCP 调用。
• 静态令牌调用方默认获得 cortex:read 权限。
• 仅当该令牌也应获得 cortex:admin 权限时，才设置 CORTEX_STATIC_TOKEN_ADMIN=true。
• OAuth 模式通过共享身份验证层支持显式的读取和管理员作用域。
• 除非配置了明确的可信网关模式，否则会拒绝绑定到非回环地址且未启用身份验证的请求。

REST

• CORTEX_API_TOKEN 与 CORTEX_TOKEN 分开。
• 未设置 API 令牌时，REST 不会挂载。
• 敏感的维护和文件尾读操作可能要求除常规 REST bearer token 外，还提供 CORTEX_API_ADMIN_TOKEN。

接收端点

• Syslog 本身不进行身份验证。请使用 CIDR 和网络控制。
• OTLP 日志、指标和追踪，以及心跳、AI 逐字稿、Shell 历史记录和 Agent 命令转发，在配置后会使用 Cortex bearer token 策略。
• 未经身份验证的转发端点仅限回环访问，除非运维人员明确建立了其他受信任边界。

数据处理

• 默认启用 AI 提示词清理。
• 清单在进入规范化缓存前会进行脱敏。
• MCP 和 REST 返回有界的证据，而不是包含原始凭据的配置文件。
• 文件尾部读取范围受配置的根目录限制，并会拒绝路径越界。
• Docker 端点和 SSH 密钥被视为特权基础设施访问权限。
• 容器示例挂载专用的最小权限 SSH 目录，而不是用户完整的 ~/.ssh。

在向回环地址或受信任网关之外公开 Cortex 之前，请阅读 docs/SECURITY.md、docs/GUARDRAILS.md 和 docs/OAUTH.md。

存储与维护

SQLite 模型

Cortex 使用 SQLite，并具备以下特性：

• WAL 模式
• 有界的 r2d2 连接池
• FTS5 外部内容索引：使用 logs_fts 索引完整日志语料库，并使用仅包含逐字稿的 ai_logs_fts 投影索引消息文本及提供方范围，以便搜索 AI 会话
• 面向常见筛选条件和时间线的覆盖索引与复合索引
• 事务性批量写入
• 持久化的源检查点和解析错误
• 维护作业跟踪
• 在线备份支持
• 完整性检查、检查点和清理工作流

当前架构历史包含 63 个连续迁移。CI 根据 KNOWN_SCHEMA_VERSION 和迁移注册表计算此分母。迁移 63 添加了索引化设备归属信息，以及有界、可恢复的后台历史处理流程，同时保留原始身份验证和会话身份信息。迁移 60 引入了仅包含逐字稿的 ai_logs_fts 投影。迁移 61 使用提供方范围重建该派生索引，并添加仅供 AI 使用的 (timestamp, ai_tool) 索引，以便有时间范围限制的会话搜索能在 FTS 扫描常见词项之前推导出安全的 rowid 下限。在大型逐字稿历史记录中，这些一次性的派生索引重建可能会在填充索引期间持有启动写事务。后续逐字稿插入和删除会增量维护 ai_logs_fts，而全局 logs_fts 仍是完整语料库的搜索索引。服务端转发回执的重放期限为七天；删除其规范证据时，回执也会一并删除。发送端暂存区的保留时间更短且有明确上限：单个来源最多保留 1,024 条记录或 1 MiB，并淘汰超过一天的记录；整个暂存区最多保留 4,096 条记录或 4 MiB。淘汰时会删除原始负载，并保留待处理的间隙标记，以便仍能看到证据丢失情况。超过服务端回执期限后的重试会被视为一次新的接收尝试。

权威数据与派生数据

权威记录包括：

• 规范化日志和原始帧
• 主机和源身份
• 逐字稿来源、检查点、导入和解析错误记录
• 心跳和组件快照
• 清单快照和采集器状态
• 错误签名和确认事件
• 技能、MCP 和钩子事件
• 通知发件箱和触发历史
• 大模型调用审计记录

派生加速数据包括：

• AI 会话汇总
• 每小时的时间线汇总
• 清单统计信息
• 流的最后出现状态
• 实体图表及证据关系

派生数据可以根据权威证据刷新或重建。

存储保护措施

守护进程会按数据块实施保留策略和逻辑数据库容量限制。在失控增长损害主机之前，它可以进入写入阻止状态，并在达到恢复阈值后恢复运行。可选的最低可用磁盘空间保护措施可防范 Cortex 数据库之外的数据造成的磁盘压力，而不会仅仅因为其他应用占满文件系统就删除 Cortex 数据。

运维命令：

cortex db status
cortex db integrity
cortex db checkpoint
cortex db backup --help
cortex db vacuum --help

维护操作（包括同步和后台完整性检查）共用一个进程级单飞门控，并与重型读取查询分别限流。并发尝试会收到可重试的忙碌响应。

部署与分发

当前标识

工件	当前标识
规范源代码仓库	dinglebear-ai/cortex
原生二进制文件和 CLI	cortex
npm 启动器	@dinglebear/cortex
MCP Registry 服务名称	ai.dinglebear/cortex
已发布的 OCI 镜像	ghcr.io/dinglebear-ai/cortex:v<version>

源代码仓库及其已发布的工件均归 dinglebear-ai 组织所有。旧版 jmagar 命名空间已弃用：scripts/check-public-identity.sh 会在任何受跟踪文件重新引入该命名空间时导致构建失败；发布工作流则会从推送所用的同一组 REGISTRY/IMAGE_NAME 推导 MCP Registry OCI 标识符，因此两者不会再次出现不一致。

迁移前发布的容器镜像仍可通过旧版命名空间读取，以支持仍固定使用旧镜像的部署，但不会再向该命名空间推送新内容。

原生版本和 npm

• 仓库提供 Linux x86_64、Linux aarch64、macOS arm64 和 Windows x86_64 发布工件。
• npm 启动器支持 linux/x64、linux/arm64、darwin/arm64 和 win32/x64，并会验证发布校验和。
• 源码构建使用 Rust edition 2024，以及 CI 中当前稳定版工具链。

Docker Compose

仓库包含：

• 用于从检出代码本地构建的 docker-compose.yml
• 用于已发布镜像的 docker-compose.prod.yml
• 用于非 root Debian 运行时镜像的 config/Dockerfile

手动使用 Compose 部署时，需要一个名为 cortex 的外部 Docker 网络，除非由 DOCKER_NETWORK 覆盖：

docker network inspect cortex >/dev/null 2>&1 || docker network create cortex
cp .env.example .env
bash scripts/prepare-compose-dirs.sh
docker compose up -d
curl -fsS http://127.0.0.1:3100/health

预检会使用 Docker Compose 自带的解析器解析 /backups 绑定挂载，并以 0700 权限创建默认目录或 CORTEX_BACKUP_DIR 覆盖目录。Compose 配置为不会隐式创建此主机路径，以防止备份目录归 root 所有或权限过于宽松。

Compose 文件：

• 通过 UDP/TCP 1514 发布 syslog
• 默认将 HTTP 发布到主机回环地址
• 将数据库持久化到稳定的命名卷或配置的绑定挂载中
• 以非 root UID/GID 运行
• 以只读方式挂载清单 SSH 凭据和工作区数据
• 以只读方式挂载专用的文件尾部读取根目录
• 默认内存限制为 2 GiB，可按主机配置
• 包含健康检查和有界容器日志

如需托管式安装和修复：

cortex setup check
cortex setup repair

主机 Agent

Cortex 提供卫星采集的设置和运行时支持，包括：

• 心跳 Agent
• Docker 流 Agent
• AI 会话监控服务和计时器
• Shell 历史记录转发
• Agent 命令转发
• 补全和调试封装程序

使用 cortex setup --help、cortex ingest --help 和 cortex heartbeat --help 查看准确的平台专属命令树。

运维

常用运维命令：

# Health and diagnostics
cortex status
cortex doctor
cortex doctor binary

# Managed setup
cortex setup check
cortex setup repair

# Database operations
cortex db status
cortex db integrity
cortex db checkpoint
cortex db backup --help
cortex db vacuum --help

# Compose lifecycle
cortex compose status
cortex compose doctor
cortex compose pull
cortex compose up
cortex compose restart
cortex compose logs

# Collection and inventory
cortex ingest inventory status --json
cortex ingest inventory refresh --json
cortex ingest filetail list
cortex sessions doctor

# Updates and configuration
cortex update --help
cortex config list
cortex completions zsh

守护进程提供精简和完整的健康状态响应，记录数据库维护作业，报告投影和采集器降级情况，并通过 CLI、REST 和 MCP 展示摄取队列与写入阻止状态。

开发与验证

工具链

该仓库使用：

• Rust edition 2024
• mise 管理固定版本的开发工具
• just 执行常见工作流
• cargo-nextest 运行隔离的 Rust 测试套件
• cargo-llvm-cov 生成覆盖率
• cargo-deny 执行依赖策略
• Lefthook 和 cargo xtask 执行本地发布和推送前检查
• 自定义的、由 soldr 支持的 Rust 编译器包装器，用于加快本地和 CI 构建

常用命令

mise install
just dev
just build
just check
just lint
just fmt
just test
just test-doc
just coverage
just coverage-html
just test-live
just validate-plugin
cargo xtask pre-push

just test-live（也可以使用 just live-smoke）是标准的、失败时默认拒绝的拉取请求测试子集。它会在由本次运行管理的拓扑中测试真实 HTTP JSON-RPC、UDP 和 TCP syslog 接收、CLI/REST 行为、浏览器路由，以及受管理的文件尾随行为。运行 just live-mcp 可测试每个已注册的 MCP 操作；定时运行的聚合测试会组合所有权威所有者配置文件。专项配置文件见实时资格验证指南。Docker 收集有独立的 Agent 部署测试，以及用于中央拉取的模拟 Docker HTTP 固定装置。

CI 门禁包括：

• 格式检查
• 启用警告拒绝的 Clippy 检查
• Nextest 和 doctest
• 版本和发行版标识同步
• MCP 集成
• npm 启动器检查
• 密钥扫描
• cargo-deny
• 覆盖率生成
• 仓库模块大小策略

有关隔离 CI 与实时集群验证的划分，请参阅 tests/TEST_COVERAGE.md 和 docs/RELEASE.md。

文档

代码所维护的注册表和运行时架构是命令名称、操作、路由、作用域、默认值和验证规则的权威依据。人工编写的文档说明如何使用这些功能。

文档	用途
AGENTS.md	跨 Agent 的权威说明；Claude/Gemini 别名为符号链接
CONTRIBUTING.md	检出、验证和贡献工作流
docs/README.md	文档索引和权威性说明
docs/ADDING_SOURCES.md	源/提供方扩展及覆盖语义
docs/repo/DOCUMENTATION.md	文档归属和偏差预防
docs/SETUP.md	安装和部署指南
docs/CONFIG.md	完整配置参考
docs/CLI.md	CLI 参考
docs/api.md	REST API 参考
docs/architecture.md	运行时和数据流架构
docs/mcp/SCHEMA.md	MCP 操作和参数架构
docs/mcp/PROMPTS.md	提示词目录
docs/SECURITY.md	汇总的信任模型
docs/OAUTH.md	OAuth 配置
docs/INVENTORY.md	组件和功能面清单
docs/RELEASE.md	发布和验证门禁
CHANGELOG.md	发布历史

带日期的设计计划和会话日志用于记录工程历史，并非当前公共接口的权威依据。操作手册属于运维指南，除非明确标注为历史文档；请对照当前源代码和配置进行核实。

当前边界

Cortex 有意采用明确的设计取舍：

• 它是单节点 SQLite 服务，而非分布式数据采集集群。
• 支持通过 HTTP/protobuf 接收 OTLP 日志、指标和追踪数据。目前尚未实现 OTLP/gRPC。
• Syslog 不会对发送方进行身份验证。网络和 CIDR 控制十分重要。
• 图谱是推导出的证据，并非权威配置状态。
• MCP 和 REST 提供有界操作，不支持任意 SQL 或未经审计的日志修改。
• 基于 LLM 的评估仅在本地运行，且需要由操作员控制、针对 CORTEX_LLM 所选提供商安装的程序。
• 集中式 Docker 拉取需要对 Docker 端点具有特权读取权限，且默认禁用。
• 资产清单的质量取决于采集器访问权限、SSH 信任、可选 API 凭据以及缓存时效。
• 随附的浏览器应用是调查工作区预览版，并非完整的监控仪表板。
• Cortex 面向家庭实验室或小型可信设备群。面向互联网或多租户部署时，必须在二进制文件之外增加隔离和策略控制。

许可证

本项目中由 Dinglebear 创作的原始部分采用 AGPL-3.0-only 许可。对于需要 AGPL 之外许可条款的组织，可提供单独的商业许可。第三方材料仍遵循其原始许可证。请参阅 LICENSING.md。