Session Weaver

解决 AI 编程助手（Cursor/Claude/Kiro 等）会话上下文丢失问题，实现跨会话、跨 AI 工具的上下文无缝交接。

核心问题

• AI 会话有 token 上限，长对话后上下文被截断
• 新开会话时，AI 完全不知道之前做了什么
• 切换不同 AI 工具时，项目上下文无法迁移
• 踩过的坑、做过的决策无法持久化传递

功能特性（7 工具架构）

| 工具 | 功能 | |------|------| | load_context | 一键加载上下文（模块 + 会话 + 踩坑），自动设置当前模块 | | save_context | 一键保存进度（更新模块 + 创建会话 + 记录踩坑） | | list_modules | 查看所有项目或项目内模块概览 | | list_pitfalls | 查看踩坑记录，支持按项目/模块/标签过滤 | | delete_data | 删除会话、踩坑、模块或整个项目 | | export_handoff | 导出全量交接文档（Markdown + JSON） | | import_handoff | 导入交接文档重建完整项目 |

快速开始

通过 npm 安装

# 全局安装
npm install -g session-weaver

# 或使用 npx（无需安装，自动更新）
npx -y session-weaver

配置 MCP 客户端

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "session-weaver": {
      "command": "npx",
      "args": ["-y", "session-weaver"]
    }
  }
}

Cursor

编辑 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "session-weaver": {
      "command": "npx",
      "args": ["-y", "session-weaver"]
    }
  }
}

其他 MCP 客户端

{
  "mcpServers": {
    "session-weaver": {
      "command": "npx",
      "args": ["-y", "session-weaver"]
    }
  }
}

使用示例

加载上下文（开始工作）

{
  "project": "my-app",
  "module": "payment",
  "sessionsLimit": 5
}

返回：模块详情、最近会话、相关踩坑记录

保存进度（完成工作）

{
  "project": "my-app",
  "moduleUpdate": {
    "removeTodos": ["微信SDK接入"],
    "addDecision": {
      "description": "选用 Stripe 而非 Paddle",
      "reason": "更好的 API 文档"
    }
  },
  "session": {
    "note": "完成微信支付 SDK 接入",
    "codeState": {
      "modifiedFiles": ["src/payment/wechat.ts"]
    }
  },
  "newPitfall": {
    "problem": "微信回调验签失败",
    "solution": "使用微信支付平台证书，不是商户证书",
    "tags": ["wechat", "webhook"]
  }
}

一键完成：更新模块待办、创建会话、记录踩坑

查看全局概览

// 列出所有项目
{}

// 查看项目内模块
{
  "project": "my-app"
}

导出让其他 AI 接手

{
  "project": "my-app"
}

生成包含全量数据的 Markdown 文档（人类可读 + 机器可解析）

导入交接文档

{
  "handoffId": "handoff-xxx"
}

或

{
  "markdown": "# 🤖 AI 会话交接文档..."
}

数据存储

所有数据存储在 ~/.session-handoff/ 目录：

~/.session-handoff/
├── projects/
│   └── {project-name}.json    # 单文件 = 项目 + 模块 + 会话 + 踩坑
└── handoffs/
    └── {handoff-id}.md        # 交接文档

单文件结构

每个项目一个 JSON 文件：

{
  "project": "my-app",
  "currentModule": "payment",
  "modules": {
    "payment": {
      "name": "payment",
      "status": "active",
      "summary": "支付宝完成，微信待接入",
      "todos": ["退款接口"],
      "decisions": [...],
      "techStack": ["stripe", "alipay-sdk"]
    }
  },
  "sessions": [...],
  "pitfalls": [...]
}

特点：

• 单文件原子写入（临时文件 + 重命名，保证数据完整性）
• 无需数据库，纯 JSON 文件，可手动编辑
• 易于备份和版本控制

上下文基于架构

传统方式：                  Session Weaver：
读取所有 session 文件   →   读取单文件
内存过滤排序            →   按模块预筛选
返回全部数据            →   返回精准上下文
AI 自行找关联           →   currentModule 自动记忆

技术栈

• Node.js >= 18 / TypeScript
• MCP SDK
• nanoid (ID 生成)
• zod (参数校验)

许可证

MIT

相关链接

• npm: https://www.npmjs.com/package/session-weaver
• MCP 协议: https://modelcontextprotocol.io