Cursor-Cortex: 面向 AI 助手的结构化记忆

适用于 Cursor、Claude Code 以及任何兼容 MCP 的 AI 助手。

解决 AI 助手记忆丢失和上下文混乱的问题。 Cursor-Cortex 为你的 AI 提供结构化思维和长期记忆，让它能够真正帮你构建软件。

🧠 AI 助手的问题

基于 LLM 的 AI 助手在生成代码和解释概念方面表现出色，但它们在以下方面存在困难：

• ❌ 记忆丢失："我们昨天在做什么？"

• ❌ 上下文切换："等等，这个项目是做什么的来着？"

• ❌ Agent 故障：迷失方向、产生幻觉、忘记目标

• ❌ 缺乏结构：在想法之间跳跃，没有系统性思考

• ❌ 知识空白：无法访问公司特定或项目特定的洞察

结果：你花在解释上下文上的时间比实际解决问题的时间更多。

Related MCP server: BuildAutomata Memory MCP Server

🎯 Cursor-Cortex 解决方案

Cursor-Cortex 为你的 AI 提供结构化外部记忆：

📋 上下文文件 → "这个项目是关于什么的？"

你的 AI 始终了解项目目标、架构决策和当前重点。

📝 分支笔记 → "我们一直在做什么？"

持续的开发日志，让你的 AI 能够在你停下的地方精确接续。

🧠 隐性知识 → "我们如何解决这类问题？"

公司特定的解决方案、模式和来之不易的洞察，这些是 LLM 所不知道的。

✅ 检查清单 → "我们的系统性方法是什么？"

结构化思维框架，让 AI（和你）保持条理清晰、考虑周全。

💡 前后对比

❌ 没有 Cursor-Cortex：

You: "Help me continue the authentication work"
AI: "I need more context. What authentication system? What issues were you facing?"
You: "Ugh, let me explain everything again..."

✅ 使用 Cursor-Cortex：

You: "Help me continue the authentication work"  
AI: *reads context + branch notes + knowledge base*
"I see you're implementing JWT refresh tokens and hit CORS issues yesterday. 
Based on our company knowledge doc about API security, let's check the middleware..."

🚀 核心优势

将你的 AI 从一个聪明的实习生转变为经验丰富的队友，它记得一切，遵循结构化思维，并且能够访问组织知识。

⚡ 完整设置指南

1. 安装依赖

npm install --legacy-peer-deps

注意： 由于 TensorFlow.js 在 v3.x 和 v4.x 版本之间存在 peer 依赖冲突，因此需要使用 --legacy-peer-deps 标志。

2. 获取完整路径

pwd
# Copy the output - you'll need it for configuration

3. 向量搜索设置（可选）

用于 AI 驱动的语义搜索功能：

系统要求：

• Node.js 18+

• 2GB 内存用于向量模型

• 500MB 磁盘空间

设置步骤：

# Step 1: Generate embeddings for all knowledge files
node generate-all-embeddings-cpu.js

# This creates vector embeddings for:
# - All tacit knowledge documents
# - All branch notes
# - All context files
# Duration varies by document count and system specs

# Step 2 (Optional): Force regenerate if content changes
node generate-all-embeddings-cpu.js --force

# Step 3 (Optional): View progress during generation
node generate-all-embeddings-cpu.js --verbose

为什么这很重要：

• 没有嵌入，语义搜索会回退到文本搜索

• 预计算的嵌入使搜索速度提高 100 倍

• 生成一次，即可用于所有语义查询

• 嵌入存储在 ~/.cursor-cortex/embeddings/ 中

4. 配置 Cursor MCP

创建或编辑 ~/.cursor/mcp.json：

"cursor-cortex": {
      "command": "node",
      "args": ["/YOUR/FULL/PATH/TO/cursor-cortex/index.js"],
      "tools": [
        "update_branch_note", 
        "add_commit_separator",
        "read_branch_notes",
        "update_context_file", 
        "read_project_context",
        "read_branch_context", 
        "list_context_files", 
        "generate_commit_message", 
        "generate_jira_comment", 
        "create_tacit_knowledge",
        "read_tacit_knowledge", 
        "search_branch_notes",
        "generate_embeddings",
        "create_completion_checklist",
        "read_checklist",
        "update_checklist",
        "sign_off_checklist",
        "archive_branch_note",
        "clear_branch_note",
        "list_all_branch_notes",
        "enhanced_branch_survey",
        "comprehensive_knowledge_search",
        "construct_project_narrative",
        "timeline_reconstruction",
        "context_sync_guidance",
        "analyze_documentation_gaps",
        "migrate_context_files",
        "request_critical_thinking_space",
        "check_critical_thinking_status",
        "request_thinking_guidance",
        "add_perspective",
        "request_synthesis_space",
        "request_synthesis_step_guidance",
        "complete_synthesis_step",
        "generate_context_zip",
        "unpack_context"
      ],
      "stdio": true,
      "env": {
        "DEBUG": "true"
      }
    },

将 /YOUR/FULL/PATH/TO/cursor-cortex/ 替换为第 2 步的输出

注意： 此配置适用于 Cursor-Cortex v1.2.0 及以上版本。如果你使用的是旧版本，某些工具可能不可用。请检查你的 package.json 版本并考虑更新。

5. 重启 Cursor

完全关闭并重新打开 Cursor。

Claude Code 安装

在你的项目根目录中创建或编辑 .claude/settings.json（或全局的 ~/.claude/settings.json）：

{
  "mcpServers": {
    "cursor-cortex": {
      "command": "node",
      "args": ["/YOUR/FULL/PATH/TO/cursor-cortex/index.js"]
    }
  }
}

将 /YOUR/FULL/PATH/TO/cursor-cortex/ 替换为第 2 步的输出，然后重启 Claude Code。

6. 启用 MCP 服务器

1. 前往 Cursor 设置（Cmd/Ctrl + ,）

2. 导航至 功能 → Model Context Protocol

3. 找到 cursor-cortex 并将其切换为开启

4. 你应该会看到：Storage directory created at /Users/yourname/.cursor-cortex

7. 测试

在任意 Cursor 聊天中，尝试：

"Update my branch notes: Testing Cursor-Cortex setup"

如果成功，你会看到：Successfully updated branch note with: "Testing Cursor-Cortex setup"

8. 知识浏览器（可视化图谱）

一切设置完成后，将你的知识库作为交互式网络图谱进行探索：

npm run explorer

然后在浏览器中打开 http://localhost:4000。

功能：

• 三层可视化：项目、分支笔记和隐性知识作为互连节点

• 相似性驱动布局：使用嵌入余弦相似度将语义相似的项目聚集在一起

• 神经脉冲动画：实时观察信号在你的知识网络中传播

• 基于活动的颜色：更亮的节点 = 最近更新的项目

• 点击探索：点击任意节点查看详情、相似项目和标签

• 深度切换：在精简视图（仅项目）、分支视图和完整视图之间切换

🔧 故障排除

常见问题：

❌ "Tool not found" 错误

• 配置后完全重启 Cursor

• 验证 MCP 服务器已在设置中启用

• 检查 mcp.json 中的文件路径是否正确（没有拼写错误）

❌ MCP 配置不工作

• 在 jsonlint.com 验证 JSON 语法

• 确保逗号和引号正确

• 检查 mcp.json 的文件权限

❌ 向量搜索不工作

• 运行 npm install 以确保 TensorFlow.js 已安装

• 检查系统是否有 2GB 以上可用内存

• 如果向量搜索失败，请尝试文本搜索模式

需要帮助？ 使用你的错误信息创建一个 issue 以获得快速支持。

9. 开始使用

• "Show my uncommitted work" - 查看你一直在做什么

• "Generate a commit message" - 从你的笔记创建提交

• "Create tacit knowledge document" - 保存解决方案以备后用

📖 基本用法

捕捉你的想法

在编码时，告诉你的 AI 助手：

"Update branch notes: Fixed the login validation bug by adding proper error handling 
for expired tokens. Had to modify the JWT middleware."

保持方向感

当你回来工作时：

"Show me my uncommitted work"

智能提交

准备好提交时：

"Generate a commit message"

AI 读取你所有的笔记并创建："Fix JWT token validation and error handling"

🏗️ 项目结构

Cursor-Cortex 将你的知识组织为：

• 📝 分支笔记：你当前正在做什么

• 📋 上下文文件：项目文档和决策

• 🧠 知识库：供未来参考的解决方案和洞察

• ✅ 检查清单：跟踪项目完成情况

全部存储在 ~/.cursor-cortex/ 中，可通过 AI 访问。

🎓 高级用户功能

当你熟悉基础知识后，可以探索这些高级功能：

跨项目知识搜索

"Search all my projects for JWT authentication solutions"

自动提交跟踪

node setup-hooks.js  # Auto-separates pre/post commit work

项目检查清单

跟踪需求、测试和验收：

"Create a completion checklist for the user auth feature"

团队知识共享

创建可复用的解决方案文档：

"Create tacit knowledge document about our JWT implementation approach"

知识考古与项目智能

分析和综合项目知识：

"Survey all my branch documentation and show completeness scores"
"Construct a project narrative for the user authentication system"
"Show me a timeline of all development across projects"
"Analyze this folder structure for documentation gaps"

🛠️ 所有可用工具

• update_branch_note - 向你的开发日志添加条目

• read_branch_notes - 默认读取完整文件（包括 COMMIT 分隔符）；mode=uncommitted 或 uncommittedOnly=true 用于读取自上次提交以来的工作；可选的 beforeDate、afterDate 或 commitHash 用于过滤

• add_commit_separator - 标记提交边界（通过 git hooks 自动完成）

• generate_commit_message - AI 从你的笔记生成提交信息

• update_context_file - 记录项目目标和决策

• read_project_context - 仅读取与分支无关的项目上下文

• read_branch_context - 仅读取特定分支的上下文

• list_context_files - 浏览所有项目文档，并显示跨项目警告

• create_tacit_knowledge - 记录解决方案以供将来参考

• read_tacit_knowledge - 使用标签和内容搜索在所有项目中搜索知识

• search_branch_notes - 使用语义搜索跨项目搜索分支笔记

• generate_embeddings - 生成或重新生成用于语义搜索的向量嵌入

• comprehensive_knowledge_search - 跨所有 Cursor-Cortex 知识的全局语义搜索

• create_completion_checklist - 跟踪需求和交付物

• read_checklist - 查看进度

• update_checklist - 将项目标记为已完成（手动或自动检测）

• sign_off_checklist - 通过签名进行正式审批

• archive_branch_note - 归档已完成的工作

• clear_branch_note - 重置分支文档

• migrate_context_files - 将现有上下文文件迁移到智能混合上下文系统

• list_all_branch_notes - 查看所有项目中按优先级排序的所有分支笔记

• enhanced_branch_survey - 对文档进行综合分析，包括完整性评分和关系映射

• construct_project_narrative - 将零散的技术细节编织成连贯的工程故事

• timeline_reconstruction - 从分支笔记和提交分隔符中提取按时间排序的时间线数据

• context_sync_guidance - 根据时间线数据获取有关同步项目上下文的指导

• analyze_documentation_gaps - 分析文件夹结构以识别文档需求并自动创建检查清单

• request_critical_thinking_space - 使用六顶思考帽方法论创建系统分析工作区

• check_critical_thinking_status - 检查批判性思维分析的完成状态

• request_thinking_guidance - 获取针对特定六顶思考帽视角的指导

• add_perspective - 向批判性思维工作区添加特定视角分析

• request_synthesis_space - 将视角加载到综合工作区以进行整合

• request_synthesis_step_guidance - 获取综合步骤的详细指导

• complete_synthesis_step - 完成特定的综合步骤并更新流程

• generate_context_zip - 将知识打包成便携式 ZIP 存档，用于在用户/环境之间共享

• unpack_context - 导入共享上下文包，并安全解决冲突

🎛️ 高级配置

Git 集成

自动提交分隔符需要 MCP 服务器正在运行：

node setup-hooks.js  # Install git hooks

CLI 界面

无需 AI 的直接访问：

node cursor-cortex-cli.js  # Interactive menu

🤝 贡献

发现 bug 或有想法？打开 issue 或提交 pull request — 欢迎贡献！

作者： Manuel Flores-Ramirez

📄 许可证

本项目采用 Parachute Public License (PPL) v1.0 许可证。

PPL 是一种道德许可证，包含禁止政府、军事、监视和其他有害实体使用的限制。有关完整详情和理由，请参阅 parachute.pub。

© 2025 Manuel Flores-Ramirez.