Cursor10x

---

概述

Cursor10x 记忆系统为 AI 助手（尤其是 Claude）创建持久记忆层，使其能够保留并回忆以下内容：

• 最近的消息和对话历史
• 当前正在处理的活动文件
• 重要的项目里程碑和决策
• 技术要求和规范
• 按时间顺序排列的操作和事件（片段）
• 代码库中的代码片段和结构
• 基于向量嵌入的语义相似内容
• 通过语义相似性关联的代码片段
• 包含函数和变量关系的文件结构

该记忆系统弥合了无状态 AI 交互与持续开发工作流之间的差距，让助手能够提供更高效、上下文感知能力更强的帮助。

系统架构

记忆系统由四个核心组件构成：

1. MCP 服务：实现 Model Context Protocol，以注册工具并处理请求
2. 记忆数据库：使用 Turso 数据库，实现跨会话持久化存储
3. 记忆子系统：将记忆划分为用途各异的专用系统
4. 向量嵌入：将文本和代码转换为数值表示，以便进行语义搜索

记忆类型

系统实现了四种互为补充的记忆类型：

1. 短期记忆（STM）

   • 存储近期消息和活动文件
   • 为当前交互提供即时上下文
   • 根据最近程度和重要性自动排序

2. 长期记忆（LTM）

   • 存储里程碑和决策等永久项目信息
   • 保留架构和设计上下文
   • 永久保存高度重要的信息

3. 情景记忆

   • 按时间顺序记录事件序列
   • 保留操作之间的因果关系
   • 为项目历史提供时间上下文

4. 语义记忆

   • 存储消息、文件和代码片段的向量嵌入
   • 根据语义相似度检索内容
   • 自动为代码结构编制索引，以便按上下文检索
   • 跟踪代码组件之间的关系
   • 支持在整个代码库中进行基于相似度的搜索

功能

• 持久化上下文：在多个会话中保留对话和项目上下文
• 基于重要性的存储：根据可配置的重要性级别优先存储信息
• 多维记忆：结合短期、长期、情景和语义记忆系统
• 全面检索：从所有记忆子系统中统一提供上下文
• 健康状况监控：内置诊断和状态报告功能
• 横幅生成：为对话开始生成信息丰富的上下文横幅
• 数据库持久化：将所有记忆数据存储在 Turso 数据库中，并自动创建架构
• 向量嵌入：为文本和代码创建数值表示，以便进行相似度搜索
• 高级向量存储：利用 Turso 的 F32_BLOB 和向量函数，高效存储嵌入
• ANN 搜索：支持近似最近邻搜索，实现快速相似度匹配
• 代码索引：自动检测并为代码结构（函数、类、变量）编制索引
• 语义搜索：根据含义而非精确文本匹配查找相关内容
• 相关性评分：根据与当前查询的相关性对上下文项进行排序
• 代码结构检测：识别并提取多种语言中的代码组件
• 自动生成嵌入：自动为已编制索引的内容创建向量嵌入
• 交叉引用检索：查找不同文件和组件中的相关代码

安装

先决条件

• Node.js 18 或更高版本
• npm 或 yarn 包管理器
• Turso 数据库账号

设置步骤

1. 配置 Turso 数据库：

# Install Turso CLI
curl -sSfL https://get.turso.tech/install.sh | bash

# Login to Turso
turso auth login

# Create a database
turso db create cursor10x-mcp

# Get database URL and token
turso db show cursor10x-mcp --url
turso db tokens create cursor10x-mcp

或者，你可以访问 Turso 注册，然后创建数据库并获取相应凭据。免费套餐完全足以满足你的项目记忆需求。

2. 配置 Cursor MCP：

在项目目录中更新 .cursor/mcp.json，填入数据库 URL 和 Turso 身份验证令牌：

{
  "mcpServers": {
    "cursor10x-mcp": {
      "command": "npx",
      "args": ["cursor10x-mcp"],
      "enabled": true,
      "env": {
        "TURSO_DATABASE_URL": "your-turso-database-url",
        "TURSO_AUTH_TOKEN": "your-turso-auth-token"
      }
    }
  }
}

工具文档

系统工具

mcp_cursor10x_initConversation

通过一次操作存储用户消息、生成横幅并检索上下文，从而初始化对话。这个统一工具取代了每次对话开始时分别调用 generateBanner、getComprehensiveContext 和 storeUserMessage 的做法。

参数：

• content（字符串，必填）：用户消息的内容
• importance（字符串，可选）：重要性级别（"low"、"medium"、"high"、"critical"），默认为 "low"
• metadata（对象，可选）：消息的其他元数据

返回值：

• 包含两个部分的对象：
  • display：包含要向用户显示的横幅
  • internal：包含供 Agent 使用的全面上下文

示例：

// Initialize a conversation
const result = await mcp_cursor10x_initConversation({
  content: "I need to implement a login system for my app",
  importance: "medium",
});
// Result: {
//   "status": "ok",
//   "display": {
//     "banner": {
//       "status": "ok",
//       "memory_system": "active",
//       "mode": "turso",
//       "message_count": 42,
//       "active_files_count": 3,
//       "last_accessed": "4/15/2023, 2:30:45 PM"
//     }
//   },
//   "internal": {
//     "context": { ... comprehensive context data ... },
//     "messageStored": true,
//     "timestamp": 1681567845123
//   }
// }

mcp_cursor10x_endConversation

通过一次调用组合多项操作来结束对话：存储助手的最终消息、记录已完成事项的里程碑，并在情景记忆中记录一个片段。这个统一工具取代了在每次对话结束时分别调用 storeAssistantMessage、storeMilestone 和 recordEpisode 的做法。

参数：

• content（string，必填）：助手最终消息的内容
• milestone_title（string，必填）：要记录的里程碑标题
• milestone_description（string，必填）：已完成事项的说明
• importance（string，可选）：重要性级别（"low"、"medium"、"high"、"critical"），默认为 "medium"
• metadata（object，可选）：所有记录的附加元数据

返回：

• 包含状态和各项操作结果的对象

示例：

// End a conversation with finalization steps
const result = await mcp_cursor10x_endConversation({
  content:
    "I've implemented the authentication system with JWT tokens as requested",
  milestone_title: "Authentication Implementation",
  milestone_description:
    "Implemented secure JWT-based authentication with refresh tokens",
  importance: "high",
});
// Result: {
//   "status": "ok",
//   "results": {
//     "assistantMessage": {
//       "stored": true,
//       "timestamp": 1681568500123
//     },
//     "milestone": {
//       "title": "Authentication Implementation",
//       "stored": true,
//       "timestamp": 1681568500123
//     },
//     "episode": {
//       "action": "completion",
//       "stored": true,
//       "timestamp": 1681568500123
//     }
//   }
// }

mcp_cursor10x_checkHealth

检查记忆系统及其数据库连接的健康状况。

参数：

• 无必填参数

返回：

• 包含健康状态和诊断信息的对象

示例：

// Check memory system health
const health = await mcp_cursor10x_checkHealth({});
// Result: {
//   "status": "ok",
//   "mode": "turso",
//   "message_count": 42,
//   "active_files_count": 3,
//   "current_directory": "/users/project",
//   "timestamp": "2023-04-15T14:30:45.123Z"
// }

mcp_cursor10x_getMemoryStats

获取记忆系统的详细统计信息。

参数：

• 无必填参数

返回：

• 包含全面记忆统计信息的对象

示例：

// Get memory statistics
const stats = await mcp_cursor10x_getMemoryStats({});
// Result: {
//   "status": "ok",
//   "stats": {
//     "message_count": 42,
//     "active_file_count": 3,
//     "milestone_count": 7,
//     "decision_count": 12,
//     "requirement_count": 15,
//     "episode_count": 87,
//     "oldest_memory": "2023-03-10T09:15:30.284Z",
//     "newest_memory": "2023-04-15T14:30:45.123Z"
//   }
// }

mcp_cursor10x_getComprehensiveContext

从所有记忆子系统获取统一上下文，整合短期记忆、长期记忆和情景记忆。

参数：

• 无必填参数

返回：

• 包含所有记忆系统整合后上下文的对象

示例：

// Get comprehensive context
const context = await mcp_cursor10x_getComprehensiveContext({});
// Result: {
//   "status": "ok",
//   "context": {
//     "shortTerm": {
//       "recentMessages": [...],
//       "activeFiles": [...]
//     },
//     "longTerm": {
//       "milestones": [...],
//       "decisions": [...],
//       "requirements": [...]
//     },
//     "episodic": {
//       "recentEpisodes": [...]
//     },
//     "system": {
//       "healthy": true,
//       "timestamp": "2023-04-15T14:30:45.123Z"
//     }
//   }
// }

短期记忆工具

mcp_cursor10x_storeUserMessage

将用户消息存储到短期记忆系统中。

参数：

• content（string，必填）：消息内容
• importance（string，可选）：重要性级别（"low"、"medium"、"high"、"critical"），默认为 "low"
• metadata（object，可选）：消息的附加元数据

返回：

• 包含状态和时间戳的对象

示例：

// Store a user message
const result = await mcp_cursor10x_storeUserMessage({
  content: "We need to implement authentication for our API",
  importance: "high",
  metadata: {
    topic: "authentication",
    priority: 1,
  },
});
// Result: {
//   "status": "ok",
//   "timestamp": 1681567845123
// }

mcp_cursor10x_storeAssistantMessage

将助手消息存储到短期记忆系统中。

参数：

• content（string，必填）：消息内容
• importance（string，可选）：重要性级别（"low"、"medium"、"high"、"critical"），默认为 "low"
• metadata（object，可选）：消息的附加元数据

返回：

• 包含状态和时间戳的对象

示例：

// Store an assistant message
const result = await mcp_cursor10x_storeAssistantMessage({
  content: "I recommend implementing JWT authentication with refresh tokens",
  importance: "medium",
  metadata: {
    topic: "authentication",
    contains_recommendation: true,
  },
});
// Result: {
//   "status": "ok",
//   "timestamp": 1681567870456
// }

mcp_cursor10x_trackActiveFile

跟踪用户正在访问或修改的活动文件。

参数：

• filename（string，必填）：要跟踪的文件路径
• action（string，必填）：对文件执行的操作（open、edit、close 等）
• metadata（object，可选）：跟踪事件的附加元数据

返回：

• 包含状态、文件名、操作和时间戳的对象

示例：

// Track an active file
const result = await mcp_cursor10x_trackActiveFile({
  filename: "src/auth/jwt.js",
  action: "edit",
  metadata: {
    changes: "Added refresh token functionality",
  },
});
// Result: {
//   "status": "ok",
//   "filename": "src/auth/jwt.js",
//   "action": "edit",
//   "timestamp": 1681567900789
// }

mcp_cursor10x_getRecentMessages

从短期记忆中获取近期消息。

参数：

• limit（number，可选）：要获取的最大消息数，默认为 10
• importance（string，可选）：按重要性级别筛选

返回：

• 包含状态和消息数组的对象

示例：

// Get recent high importance messages
const messages = await mcp_cursor10x_getRecentMessages({
  limit: 5,
  importance: "high",
});
// Result: {
//   "status": "ok",
//   "messages": [
//     {
//       "id": 42,
//       "role": "user",
//       "content": "We need to implement authentication for our API",
//       "created_at": "2023-04-15T14:30:45.123Z",
//       "importance": "high",
//       "metadata": {"topic": "authentication", "priority": 1}
//     },
//     ...
//   ]
// }

mcp_cursor10x_getActiveFiles

从短期记忆中获取活动文件。

参数：

• limit（number，可选）：要获取的最大文件数，默认为 10

返回：

• 包含状态和活动文件数组的对象

示例：

// Get recent active files
const files = await mcp_cursor10x_getActiveFiles({
  limit: 3,
});
// Result: {
//   "status": "ok",
//   "files": [
//     {
//       "id": 15,
//       "filename": "src/auth/jwt.js",
//       "last_accessed": "2023-04-15T14:30:45.123Z",
//       "metadata": {"changes": "Added refresh token functionality"}
//     },
//     ...
//   ]
// }

长期记忆工具

mcp_cursor10x_storeMilestone

将项目里程碑存储在长期记忆中。

参数：

• title (string，必填)：里程碑标题
• description (string，必填)：里程碑描述
• importance (string，可选)：重要性级别，默认为 "medium"
• metadata (object，可选)：里程碑的其他元数据

返回：

• 包含状态、标题和时间戳的对象

示例：

// Store a project milestone
const result = await mcp_cursor10x_storeMilestone({
  title: "Authentication System Implementation",
  description:
    "Implemented JWT authentication with refresh tokens and proper error handling",
  importance: "high",
  metadata: {
    version: "1.0.0",
    files_affected: ["src/auth/jwt.js", "src/middleware/auth.js"],
  },
});
// Result: {
//   "status": "ok",
//   "title": "Authentication System Implementation",
//   "timestamp": 1681568000123
// }

mcp_cursor10x_storeDecision

将项目决策存储在长期记忆中。

参数：

• title (string，必填)：决策标题
• content (string，必填)：决策内容
• reasoning (string，可选)：决策背后的推理
• importance (string，可选)：重要性级别，默认为 "medium"
• metadata (object，可选)：决策的其他元数据

返回：

• 包含状态、标题和时间戳的对象

示例：

// Store a project decision
const result = await mcp_cursor10x_storeDecision({
  title: "JWT for Authentication",
  content: "Use JWT tokens for API authentication with refresh token rotation",
  reasoning:
    "JWTs provide stateless authentication with good security and performance characteristics",
  importance: "high",
  metadata: {
    alternatives_considered: ["Session-based auth", "OAuth2"],
    decision_date: "2023-04-15",
  },
});
// Result: {
//   "status": "ok",
//   "title": "JWT for Authentication",
//   "timestamp": 1681568100456
// }

mcp_cursor10x_storeRequirement

将项目需求存储在长期记忆中。

参数：

• title (string，必填)：需求标题
• content (string，必填)：需求内容
• importance (string，可选)：重要性级别，默认为 "medium"
• metadata (object，可选)：需求的其他元数据

返回：

• 包含状态、标题和时间戳的对象

示例：

// Store a project requirement
const result = await mcp_cursor10x_storeRequirement({
  title: "Secure Authentication",
  content:
    "System must implement secure authentication with password hashing, rate limiting, and token rotation",
  importance: "critical",
  metadata: {
    source: "security audit",
    compliance: ["OWASP Top 10", "GDPR"],
  },
});
// Result: {
//   "status": "ok",
//   "title": "Secure Authentication",
//   "timestamp": 1681568200789
// }

情景记忆工具

mcp_cursor10x_recordEpisode

在情景记忆中记录一个事件（操作）。

参数：

• actor (string，必填)：执行操作的主体（user、assistant、system）
• action (string，必填)：执行的操作类型
• content (string，必填)：操作的内容或详情
• importance (string，可选)：重要性级别，默认为 "low"
• context (string，可选)：事件的上下文

返回：

• 包含状态、主体、操作和时间戳的对象

示例：

// Record an episode
const result = await mcp_cursor10x_recordEpisode({
  actor: "assistant",
  action: "implementation",
  content: "Created JWT authentication middleware with token verification",
  importance: "medium",
  context: "authentication",
});
// Result: {
//   "status": "ok",
//   "actor": "assistant",
//   "action": "implementation",
//   "timestamp": 1681568300123
// }

mcp_cursor10x_getRecentEpisodes

从情景记忆中检索近期事件。

参数：

• limit (number，可选)：要检索的事件数上限，默认为 10
• context (string，可选)：按上下文筛选

返回：

• 包含状态和事件数组的对象

示例：

// Get recent episodes in the authentication context
const episodes = await mcp_cursor10x_getRecentEpisodes({
  limit: 5,
  context: "authentication",
});
// Result: {
//   "status": "ok",
//   "episodes": [
//     {
//       "id": 87,
//       "actor": "assistant",
//       "action": "implementation",
//       "content": "Created JWT authentication middleware with token verification",
//       "timestamp": "2023-04-15T14:45:00.123Z",
//       "importance": "medium",
//       "context": "authentication"
//     },
//     ...
//   ]
// }

基于向量的记忆工具

mcp_cursor10x_manageVector

用于管理向量嵌入的统一工具，支持存储、搜索、更新和删除操作。

参数：

• operation (string，必填)：要执行的操作（"store"、"search"、"update"、"delete"）
• contentId (number，可选)：此向量所表示内容的 ID（用于 store、update、delete）
• contentType (string，可选)：内容类型（"message"、"file"、"snippet" 等）
• vector (array，可选)：由数字组成的数组形式的向量数据（用于 store、update）或查询向量（用于 search）
• vectorId (number，可选)：要更新或删除的向量 ID
• limit (number，可选)：search 操作的结果数上限，默认为 10
• threshold (number，可选)：search 操作的相似度阈值，默认为 0.7
• metadata (object，可选)：向量的其他信息

返回：

• 包含状态和操作结果的对象

示例：

// Store a vector embedding
const result = await mcp_cursor10x_manageVector({
  operation: "store",
  contentId: 42,
  contentType: "message",
  vector: [0.1, 0.2, 0.3, ...], // 128-dimensional vector
  metadata: {
    topic: "authentication",
    language: "en"
  }
});
// Result: {
//   "status": "ok",
//   "operation": "store",
//   "vectorId": 15,
//   "timestamp": 1681570000123
// }

// Search for similar vectors
const searchResult = await mcp_cursor10x_manageVector({
  operation: "search",
  vector: [0.1, 0.2, 0.3, ...], // query vector
  contentType: "snippet", // optional filter
  limit: 5,
  threshold: 0.8
});
// Result: {
//   "status": "ok",
//   "operation": "search",
//   "results": [
//     {
//       "vectorId": 10,
//       "contentId": 30,
//       "contentType": "snippet",
//       "similarity": 0.92,
//       "metadata": { ... }
//     },
//     ...
//   ]
// }

数据库架构

记忆系统会自动创建并维护以下数据库表：

• messages：存储用户和助手消息

  • id：唯一标识符
  • timestamp：创建时间戳
  • role：消息角色（user/assistant）
  • content：消息内容
  • importance：重要性级别
  • archived：消息是否已归档

• active_files：跟踪文件活动

  • id：唯一标识符
  • filename：文件路径
  • action：上次执行的操作
  • last_accessed：上次访问的时间戳

• milestones：记录项目里程碑

  • id：唯一标识符
  • title：里程碑标题
  • description：详细描述
  • timestamp：创建时间戳
  • importance：重要性级别

• decisions：存储项目决策

  • id：唯一标识符
  • title：决策标题
  • content：决策内容
  • reasoning：决策理由
  • timestamp：创建时间戳
  • importance：重要性级别

• requirements：维护项目需求

  • id：唯一标识符
  • title：需求标题
  • content：需求内容
  • timestamp：创建时间戳
  • importance：重要性级别

• episodes：记录操作和事件

  • id：唯一标识符
  • timestamp：创建时间戳
  • actor：执行操作的参与者
  • action：操作类型
  • content：操作详情
  • importance：重要性级别
  • context：操作上下文

• vectors：存储用于语义搜索的向量嵌入

  • id：唯一标识符
  • content_id：所引用内容的 ID
  • content_type：内容类型（message、file、snippet）
  • vector：嵌入向量的二进制表示
  • metadata：向量的其他元数据

• code_files：跟踪已索引的代码文件

  • id：唯一标识符
  • file_path：文件路径
  • language：编程语言
  • last_indexed：上次索引的时间戳
  • metadata：其他文件元数据

• code_snippets：存储提取的代码结构

  • id：唯一标识符
  • file_id：对父文件的引用
  • start_line：起始行号
  • end_line：结束行号
  • symbol_type：代码结构类型（函数、类、变量）
  • content：代码片段内容

工作流示例

优化对话启动

// Initialize conversation with a single tool call
// This replaces the need for three separate calls at the start of the conversation
const result = await mcp_cursor10x_initConversation({
  content: "I need help implementing authentication in my React app",
  importance: "high",
});

// Display the banner to the user
console.log("Memory System Status:", result.display.banner);

// Use the context internally (do not show to user)
const context = result.internal.context;
// Use context for more informed assistance

开始新会话（替代方法）

// Generate a memory banner at the start
mcp_cursor10x_generateBanner({});

// Get comprehensive context
mcp_cursor10x_getComprehensiveContext({});

// Store the user message
mcp_cursor10x_storeUserMessage({
  content: "I need help with authentication",
  importance: "high",
});

跟踪用户活动

// Track an active file
await mcp_cursor10x_trackActiveFile({
  filename: "src/auth/jwt.js",
  action: "edit",
});

故障排除

常见问题

1. 数据库连接问题

   • 确认 Turso 数据库 URL 和身份验证令牌正确无误
   • 检查与 Turso 服务的网络连接
   • 确认防火墙设置允许连接

2. 数据缺失

   • 检查数据是否以适当的重要性级别存储
   • 确认检索查询参数（限制、筛选器）
   • 使用 mcp_cursor10x_checkHealth() 检查数据库健康状态

3. 性能问题

   • 使用 mcp_cursor10x_getMemoryStats() 监控内存统计信息
   • 如果数据库增长过大，可考虑归档旧数据
   • 使用更具体的筛选器优化检索

诊断步骤

1. 检查系统健康状态：

   const health = await mcp_cursor10x_checkHealth({});
   console.log("System Health:", health);
   

2. 验证内存统计信息：

   const stats = await mcp_cursor10x_getMemoryStats({});
   console.log("Memory Stats:", stats);
   

3. 生成状态横幅：

   const banner = await mcp_cursor10x_generateBanner({});
   console.log("Memory Banner:", banner);
   

重要性级别

将项目存储到记忆中时，请使用适当的重要性级别：

• low：一般信息、常规操作、日常对话
• medium：有用的上下文、标准工作项、常规功能
• high：关键决策、主要功能、重要架构元素
• critical：核心架构、安全问题、数据完整性问题

许可证

MIT