IDE Memory MCP

IDE Memory MCP

跨 IDE 的 AI 编码 Agent 持久记忆 — 你的 AI 会记住每个项目，无论使用哪款 IDE。

问题

每次你在新的 IDE 中打开项目，或开始一段全新的 AI 对话时，AI 助手都会忘记所有内容：

• 项目的用途
• 你做出的架构决策
• 你当前正在做的工作
• 你的进度和里程碑

你只能反复重复。每次。都是如此。

解决方案

IDE Memory MCP 为 AI 编码 Agent 提供一个可跨任何支持 Model Context Protocol 的 IDE 使用的持久记忆层。只需编写一次项目上下文 — AI 就能在任何地方记住它。

Cursor ←──→ IDE Memory MCP ←──→ VS Code
   ↑              ↓                 ↑
   └── same project memory ────────┘

主要功能

• 跨 IDE 记忆 — 项目上下文可在 Cursor、VS Code、Windsurf、Claude Desktop 以及任何兼容 MCP 的 IDE 中持久保存
• 上下文优化 — 默认读取会返回精简的摘要表，而非会撑爆上下文窗口的内容转储。AI 只加载所需内容。
• 智能警告 — 自动检测过期章节（>7 天）、内容过大（>10k 字符），并在记忆过旧（>30 天）时建议精简
• Agent 提示词 — 内置 MCP 提示词，引导 AI 如何开始会话、为新项目初始化记忆，以及在更改后更新记忆
• 智能项目匹配 — 可通过路径或 git 远程 URL 识别项目。移动文件夹、更换设备，记忆都会随之迁移。
• 基于章节的存储 — 按 overview、decisions、active_context、progress 和自定义章节整理
• 追加模式 — 增量添加更新，无需重写整个章节
• 版本历史 — 每次覆盖前自动保存旧内容（保留最近 5 个快照）
• 零配置 — 开箱即用。无需数据库或云服务，只使用本地 Markdown 文件。

快速开始

1. 安装

# Using uv (recommended)
uv pip install ide-memory-mcp

# Using pip
pip install ide-memory-mcp

2. 自动配置 IDE

运行设置命令，自动检测并配置已安装的 IDE（Cursor、VS Code、Windsurf、Claude Desktop）：

ide-memory-mcp setup

💡 运行此命令后，请重启 IDE 以激活 MCP 服务。

CLI 命令

ide-memory-mcp 包含实用命令，可用于管理设置：

ide-memory-mcp setup

自动为 IDE 配置 MCP。

ide-memory-mcp setup              # auto-detect + configure all
ide-memory-mcp setup --cursor     # configure only Cursor
ide-memory-mcp setup --vscode     # configure only VS Code
ide-memory-mcp setup --windsurf   # configure only Windsurf
ide-memory-mcp setup --claude     # configure only Claude Desktop
ide-memory-mcp setup --all        # configure all supported

ide-memory-mcp doctor

检查安装状态。

ide-memory-mcp doctor

验证服务导入、存储磁盘用量、项目数量，以及已配置的 IDE。

ide-memory-mcp status

快速查看所有项目概况。

ide-memory-mcp status

列出已注册项目的章节数量、总大小和最后更新时间。

{
  "mcpServers": {
    "ide-memory": {
      "command": "ide-memory-mcp"
    }
  }
}

{
  "mcpServers": {
    "ide-memory": {
      "command": "ide-memory-mcp"
    }
  }
}

{
  "mcpServers": {
    "ide-memory": {
      "command": "ide-memory-mcp"
    }
  }
}

{
  "mcpServers": {
    "ide-memory": {
      "command": "ide-memory-mcp"
    }
  }
}

工具

IDE Memory MCP 向 AI Agent 提供 4 个经过优化的工具：

init_project

注册或重新连接到项目。每次对话都要先调用此工具。

init_project(projectPath, projectName?, gitRemoteUrl?)

• 新项目 → 创建记忆存储、建议后续步骤，并提及 bootstrap_memory 提示词
• 已知项目 → 重新连接，并返回记忆摘要及智能警告：
  • ⚠️ 需要填充的空白部分
  • ⏰ 需要更新的过时部分（>7 天）
  • 📦 可能需要精简的大型部分（>10k 字符）
  • 🧹 建议全面清理的旧部分（>30 天）

read_memory

根据上下文加载记忆。经过优化，可避免 AI 的上下文窗口被内容淹没。

read_memory(projectIdOrPath, sections?, query?, maxChars?, history?, prune?)

💡 推荐工作流：

1. read_memory(projectId) → 获取摘要表（约 10 行）
2. 确定哪些部分与当前任务相关
3. read_memory(projectId, sections=["overview", "decisions"]) → 仅加载所需内容

write_memory

写入一个或多个记忆部分。

write_memory(projectIdOrPath, sections, append?, heading?)

• 覆盖模式（默认）：替换整个部分的内容。之前的内容会自动保存到历史记录中。
• 追加模式（append=True）：添加带时间戳的条目，无需重写内容。非常适合记录决策和进度。

工具描述中包含行为指导，会告知 AI Agent 何时调用此工具：

• 完成重大代码更改后
• 做出重要决策时
• 高效工作会话结束时
• 用户要求“记住”某些内容时

manage_projects

列出或删除项目。

manage_projects(action, projectIdOrPath?, confirm?)

MCP 提示词

IDE Memory MCP 包含 3 个内置提示词模板，可引导 AI Agent 执行常见工作流。这些模板解决了“Agent 不知道何时使用记忆”的问题。

start_session

适用时机： 每次对话开始时。

引导 Agent 执行以下操作：初始化项目 → 阅读摘要 → 加载相关部分 → 检查过时内容 → 规划会话结束时的记忆更新。

bootstrap_memory

适用时机： 首次在现有项目中使用 IDE Memory，或用户说 “了解这个项目” 时。

引导 Agent 执行以下操作：分析 README 和包文件 → 编写全面的概述 → 记录架构决策 → 设置活动上下文 → 记录进度。

update_memory

适用时机： 高效工作会话结束时、完成重大更改后，或用户说 “保存我们刚才做的工作” 时。

引导 Agent 执行以下操作：读取当前记忆 → 更新 active_context → 追加新的决策 → 更新进度 → 根据需要更新概述 → 检查是否需要清理。

记忆部分

为每个项目创建的默认部分：

完全支持自定义部分——可使用任意小写标识符：

write_memory(projectId, {"api_contracts": "...", "testing_notes": "..."})

智能警告

记忆摘要会自动包含可执行的警告：

存储

所有记忆都以简单的 Markdown 文件形式存储在 ~/.ide-memory/projects/ 中：

~/.ide-memory/
├── config.json              # Optional configuration
└── projects/
    └── <project_id>/
        ├── meta.json         # Project metadata + timestamps
        ├── overview.md
        ├── decisions.md
        ├── active_context.md
        ├── progress.md
        └── .history/         # Auto-saved snapshots
            ├── overview_20260314_120000.md
            └── decisions_20260314_130000.md

• 无需数据库
• 所有文件都是人类可读的 Markdown
• 易于备份、版本管理或迁移
• 数据永远不会离开你的设备

配置

可选。创建 ~/.ide-memory/config.json：

{
  "default_sections": [
    "overview",
    "decisions",
    "active_context",
    "progress"
  ]
}

开发

前置条件

• Python 3.11+
• uv（推荐）或 pip

设置

git clone https://github.com/prasanna-pmpeople/IDE-Memory-MCP.git
cd IDE-Memory-MCP
uv sync

运行服务

uv run ide-memory-mcp

运行测试

uv run pytest tests/ -v

使用 MCP Inspector 测试

npx -y @modelcontextprotocol/inspector uv run ide-memory-mcp

完整测试指南请参阅 TESTING.md，其中包括 MCP Inspector 操作指南和跨 IDE 实战测试。

构建软件包

uv build

从构建好的软件包安装

pip install dist/ide_memory_mcp-1.0.0-py3-none-any.whl

工作原理