Cognetivy

官网： cognetivy.com

Cognetivy 是一个为 Claude Code、Cursor、OpenClaw 等 AI 助手提供的开源状态层（State Layer）。它能帮助你定义工作流、追踪运行过程与事件，并在本地 .cognetivy/ 工作区中存储结构化的集合。它本身不包含 LLM，只是通过 Skills 和 MCP 为编辑器中的 Agent 提供数据与工具支持。兼容 Claude Code、Cursor、OpenClaw 以及其他支持 Skills 和 MCP 的客户端。

Star History

为什么选择 Cognetivy

AI 编程 Agent 在生成输出方面表现出色，但其处理过程通常难以检查且难以复现。

Cognetivy 为你的 Agent 提供了一个操作层，使你能够：

• 定义运行方式：通过明确的工作流进行规范。
• 追踪运行过程：记录每次运行和事件的发生情况。
• 组织推理成果：将推理工件保存在结构化的集合中。
• 重复运行与对比结果：借助持久化的本地工作区进行分析。

简而言之：Cognetivy 将强大但混乱的 Agent 会话转化为结构化、可审计的工作流。

演示

给新手的通俗解释

将你的编程 Agent 想象成一个非常聪明的实习生：

• 模型是大脑。
• 编辑器是工作台。
• Cognetivy 是记忆 + 流程管理器。

如果没有 Cognetivy，大量重要的上下文信息仅存在于聊天记录中，随后便会消失。 使用 Cognetivy 后，这些工作会被捕获为工作流、运行记录、事件和集合，并保存到 .cognetivy/ 中。

项目状态： 积极维护中。欢迎提交 Issues 和 Pull Requests。

适用场景：

• 构建可复现的 AI 编程工作流。
• 使用编程 Agent 执行结构化的研究任务。
• 需要对 Agent 输出进行追溯和审计的团队。

系统要求

• Node.js ≥ 18
• 项目目录（或用于创建工作区的空文件夹）
• 在该目录下工作的编程 Agent（如 Claude Code, Cursor, OpenClaw 等）

---

安装

使用 npx 运行（无需全局安装）：

npx cognetivy

或者进行全局安装，以便在任何目录下使用以及支持 MCP：

npm install -g cognetivy

---

操作指南

第 1 步 - 运行 Cognetivy

在项目文件夹（或空文件夹）中打开终端并运行：

npx cognetivy

安装程序将在终端中启动：

---

第 2 步 - 使用安装程序

1. 在安装程序中，选择你的编程 Agent（Claude Code、Cursor、OpenClaw 等）。
2. Cognetivy 将在当前文件夹中创建 .cognetivy/ 工作区。
3. Cognetivy 将安装其技能（Skills）到该工作区中。

---

第 3 步 - 打开 Studio

安装完成后，Cognetivy Studio 将在浏览器中打开。

你将看到只读界面，包含工作流、运行记录和集合。

---

第 4 步 - 让 Agent 创建并运行工作流

在另一个聊天窗口中，让你的 Agent 创建一个工作流并运行它：

• “创建一个包含三个节点的工作流：一个用于收集需求，一个用于编写计划，一个用于编写摘要。将其保存为当前工作流。”
• “启动当前工作流的运行，输入主题为‘用户入门’。”

连接你的 Agent (MCP)

Cognetivy 与 Agent Skills 配合使用效果最佳，但你也可以通过 MCP 进行连接，以便在聊天中调用 Cognetivy 工具。

Cursor

1. 打开 Settings → Tools & MCP（或 Features → MCP）。
2. 点击 Add new MCP server。
3. Name 设置为 cognetivy。
4. Command 设置为 cognetivy（如果不在 PATH 中，请填写完整路径）。
5. Arguments 设置为 mcp。如果你的项目根目录不是包含 .cognetivy/ 的文件夹，请添加 --workspace 并指定该文件夹路径（例如 --workspace ./example-usage）。
6. 保存并重启 Cursor。

之后，Cognetivy 工具（workflow, run, event, collection, node 等）即可在聊天中使用。

可选 - 配置文件： 你也可以将服务器配置添加到 ~/.cursor/mcp.json（或项目下的 .cursor/mcp.json）：

{
  "mcpServers": {
    "cognetivy": {
      "command": "cognetivy",
      "args": ["mcp"]
    }
  }
}

如果工作区不是当前项目根目录，请使用 "args": ["mcp", "--workspace", "/path/to/folder/with/.cognetivy"]。

工作流模板（新功能）

使用基于 Cognetivy 实用场景的内置模板：

cognetivy workflow templates
cognetivy workflow apply-template            # 交互式选择器（创建工作流 + 设置为当前）
cognetivy workflow apply-template --id bug-triage-and-fix
cognetivy workflow template --id bug-triage-and-fix > workflow.template.json
cognetivy workflow set --wo