Memory Journal MCP

🚀 记忆日志MCP服务器

记忆日志MCP服务器用于AI辅助开发中的项目上下文管理，借助持久化知识图谱和智能上下文召回功能，弥合碎片化AI线程之间的差距。

项目链接

• GitHub
• Wiki
• 更新日志
• 发布文章

快速部署

• npm包 - npm install -g memory-journal-mcp
• Docker Hub - 基于Alpine，支持全语义搜索

版本信息

最后更新于2025年12月28日 - v3.0.0

项目徽章

🚀 快速开始

选项1：npm（推荐）

步骤1：安装包

npm install -g memory-journal-mcp

步骤2：添加到~/.cursor/mcp.json

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

步骤3：重启Cursor 重启Cursor或MCP客户端，然后开始记录日志！

选项2：npx（无需安装）

{
  "mcpServers": {
    "memory-journal-mcp": {
      "command": "npx",
      "args": ["-y", "memory-journal-mcp"]
    }
  }
}

选项3：从源代码安装

git clone https://github.com/neverinfamous/memory-journal-mcp.git
cd memory-journal-mcp
npm install
npm run build

{
  "mcpServers": {
    "memory-journal-mcp": {
      "command": "node",
      "args": ["dist/cli.js"]
    }
  }
}

GitHub集成配置

GitHub工具（如get_github_issues、get_github_prs等）可以从Git上下文自动检测仓库。但是，MCP客户端可能会从与项目不同的目录运行服务器。

要启用GitHub自动检测，请在配置中添加GITHUB_REPO_PATH：

{
  "mcpServers": {
    "memory-journal-mcp": {
      "command": "memory-journal-mcp",
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here",
        "GITHUB_REPO_PATH": "/path/to/your/git/repo"
      }
    }
  }
}

如果没有GITHUB_REPO_PATH：在调用GitHub工具时，需要明确提供owner和repo参数。

Cursor已知问题

列出MCP资源：如果代理在列出资源时遇到问题，请指示它调用list_mcp_resources()而不指定服务器参数。使用server="memory-journal-mcp"可能会返回空结果（Cursor的bug）。

✨ v3.0.0（2025年12月28日）有哪些新特性

🚀 完全用TypeScript重写

记忆日志v3.0是用TypeScript从头开始重写的，具备以下特性：

• 纯JS栈 - 无需本地编译（sql.js + vectra + @xenova/transformers）
• 跨平台可移植性 - 无需二进制依赖，可在Windows、macOS、Linux上运行
• 严格的类型安全 - 零TypeScript错误，100%严格模式合规
• 更快的启动速度 - 延迟加载ML模型，实现即时冷启动
• 符合MCP 2025-11-25规范 - 完全符合规范并带有行为注释

🗄️ 新增：备份与恢复工具

再也不用担心丢失日志数据：

// 在进行重大更改之前创建备份
backup_journal({ name: "before_migration" })
// → { success: true, filename: "before_migration.db", sizeBytes: 524288 }

// 列出可用的备份
list_backups()
// → { backups: [...], total: 3, backupsDirectory: "~/.memory-journal/backups" }

// 从备份中恢复（需要确认）
restore_backup({ filename: "before_migration.db", confirm: true })
// → { success: true, previousEntryCount: 50, newEntryCount: 42 }

📊 新增：服务器健康资源

通过memory://health获取全面的服务器诊断信息：

{
  "database": {
    "path": "~/.memory-journal/memory_journal.db",
    "sizeBytes": 524288,
    "entryCount": 150,
    "deletedEntryCount": 5,
    "relationshipCount": 42,
    "tagCount": 28
  },
  "backups": {
    "directory": "~/.memory-journal/backups",
    "count": 3,
    "lastBackup": { "filename": "...", "createdAt": "...", "sizeBytes": 524288 }
  },
  "vectorIndex": {
    "available": true,
    "indexedEntries": 150,
    "modelName": "all-MiniLM-L6-v2"
  },
  "toolFilter": {
    "active": false,
    "enabledCount": 27,
    "totalCount": 27
  },
  "timestamp": "2025-12-28T05:47:00Z"
}

📈 当前功能

• 27个MCP工具 - 完整的开发工作流 + 备份/恢复功能
• 14个工作流提示 - 包括站会、回顾、PR工作流、CI/CD故障分析等
• 14个MCP资源 - 包括新的memory://health诊断信息
• GitHub集成 - 支持项目、问题、拉取请求、操作，并自动链接
• 8个工具组 - core、search、analytics、relationships、export、admin、github、backup
• 知识图谱 - 5种关系类型，支持Mermaid可视化
• 语义搜索 - 通过@xenova/transformers实现AI驱动的概念搜索

🎯 为什么选择记忆日志？

碎片化AI上下文问题

在使用AI辅助管理大型项目时，会面临以下关键挑战：

• 线程失忆 - 每次新的AI对话都从零开始，不了解之前的工作
• 上下文丢失 - 决策、实现和学习成果分散在不相关的线程中
• 重复工作 - AI建议的解决方案可能是你已经尝试或放弃的
• 上下文过载 - 需要手动将项目历史复制到每个新对话中

解决方案：持久化项目记忆

记忆日志充当项目的长期记忆，弥合碎片化AI线程之间的差距： 对于开发者：

• 📝 自动上下文捕获 - 每次记录时自动捕获Git提交、分支、GitHub问题、PR和项目状态
• 🔗 知识图谱 - 关联相关工作（规范 → 实现 → 测试 → PR），构建连贯的历史记录
• 🔍 智能搜索 - 在整个项目时间线中查找过去的决策、解决方案和上下文
• 📊 项目分析 - 跟踪从问题到PR的进度，生成站会/回顾报告

对于AI辅助工作：

• 💡 AI可以在任何对话中查询你的完整项目历史
• 🧠 语义搜索可以找到概念相关的工作，即使没有确切的关键词
• 📖 上下文包可以立即为AI提供全面的项目状态
• 🔗 关系可视化展示不同工作之间的连接方式

📋 核心功能

🛠️ 27个MCP工具（8个组）

完整工具参考 →

🎯 14个工作流提示

• find-related - 通过语义相似度发现相关条目
• prepare-standup - 每日站会总结
• prepare-retro - 冲刺回顾
• weekly-digest - 按天的每周总结
• analyze-period - 深入的时间段分析和洞察
• goal-tracker - 里程碑和成就跟踪
• get-context-bundle - 包含Git/GitHub的项目上下文
• pr-summary - 拉取请求日志活动总结
• code-review-prep - 全面的PR审查准备
• pr-retrospective - 完成的PR分析和学习经验
• actions-failure-digest - CI/CD故障分析

完整提示指南 →

📡 14个资源

• memory://recent - 10条最近的条目
• memory://significant - 重要的里程碑和突破
• memory://graph/recent - 最近关系的实时Mermaid图
• memory://team/recent - 最近团队共享的条目
• memory://health - 新增 服务器健康和诊断信息
• memory://projects/{number}/timeline - 项目活动时间线
• memory://issues/{issue_number}/entries - 与问题关联的条目
• memory://prs/{pr_number}/entries - 与PR关联的条目
• memory://prs/{pr_number}/timeline - 合并的PR + 日志时间线
• memory://graph/actions - CI/CD叙事图
• memory://actions/recent - 最近的工作流运行
• memory://tags - 所有标签及其使用次数
• memory://statistics - 日志统计信息

🔧 配置

GitHub集成（可选）

export GITHUB_TOKEN="your_token"              # 用于项目/问题/PR
export GITHUB_ORG_TOKEN="your_org_token"      # 可选：组织项目
export DEFAULT_ORG="your-org-name"            # 可选：默认组织

权限范围：repo, project, read:org（仅组织）

工具过滤（可选）

使用MEMORY_JOURNAL_MCP_TOOL_FILTER控制暴露哪些工具：

export MEMORY_JOURNAL_MCP_TOOL_FILTER="-analytics,-github"

过滤语法：

• -group - 禁用组中的所有工具
• -tool - 禁用特定工具
• +tool - 在禁用组后重新启用工具
• 元组：starter, essential, full, readonly

示例配置：

{
  "mcpServers": {
    "memory-journal-mcp": {
      "command": "memory-journal-mcp",
      "env": {
        "MEMORY_JOURNAL_MCP_TOOL_FILTER": "starter",
        "GITHUB_TOKEN": "your_token"
      }
    }
  }
}

完整工具过滤指南 →

💻 使用示例

创建带有GitHub上下文的条目

create_entry({
  content: "Completed Phase 1 of GitHub Projects integration!",
  entry_type: "technical_achievement",
  tags: ["github-projects", "milestone"],
  project_number: 1,
  significance_type: "technical_breakthrough"
})

创建和管理备份

// 在进行重大重构之前
backup_journal({ name: "pre_refactor" })

// 检查可用的备份
list_backups()

// 需要时恢复（先自动备份）
restore_backup({ filename: "pre_refactor.db", confirm: true })

检查服务器健康状况

// 获取健康资源
// 返回：数据库统计信息、备份信息、向量索引状态、工具过滤配置

搜索和分析

// 全文搜索
search_entries({ query: "performance optimization", limit: 5 })

// 概念的语义搜索
semantic_search({ query: "startup time improvements", limit: 3 })

// 获取分析数据
get_statistics({ group_by: "week" })

生成可视化地图

// 可视化条目关系
visualize_relationships({
  entry_id: 55,
  depth: 2
})

🏗️ 架构

┌─────────────────────────────────────────────────────────────┐
│ MCP服务器层（TypeScript）                               │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────┐  │
│  │ 工具（27个）      │  │ 资源（14个）  │  │ 提示（14个）│  │
│  │ 带有注释         │  │ 带有注释      │  │             │  │
│  └─────────────────┘  └─────────────────┘  └─────────────┘  │
├─────────────────────────────────────────────────────────────┤
│ 纯JS栈（无本地依赖）                      │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────┐  │
│  │ sql.js          │  │ vectra          │  │ transformers│  │
│  │ （SQLite）      │  │ （向量索引）  │  │ （嵌入）    │  │
│  └─────────────────┘  └─────────────────┘  └─────────────┘  │
├─────────────────────────────────────────────────────────────┤
│ 带有混合搜索的SQLite数据库                          │
│  ┌─────────────────────────────────────────────────────────┐│
│  │ 条目 + 标签 + 关系 + 嵌入 + 备份   ││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘

🔧 技术亮点

性能与可移植性

• TypeScript + 纯JS栈 - 无需本地编译，可在任何地方运行
• sql.js - 纯JavaScript实现的SQLite，支持磁盘同步
• vectra - 无需本地依赖的向量相似度搜索
• @xenova/transformers - JavaScript实现的ML嵌入
• 延迟加载 - ML模型在首次使用时加载，而不是在启动时

安全性

• 本地优先 - 所有数据本地存储，无需外部API调用（可选的GitHub除外）
• 输入验证 - 使用Zod模式，限制内容大小，防止SQL注入
• 路径遍历保护 - 验证备份文件名
• MCP 2025-11-25注释 - 行为提示（readOnlyHint, destructiveHint等）

数据与隐私

• 单个SQLite文件 - 数据归你所有
• 可移植性 - 可以将.db文件移动到任何地方
• 软删除 - 条目可以恢复
• 恢复时自动备份 - 避免意外丢失数据

📚 文档与资源

• GitHub Wiki - 完整文档
• Docker Hub - 容器镜像
• npm包 - Node.js发行版
• 问题反馈 - 报告bug和提出功能请求

📄 许可证

本项目采用MIT许可证，详情请见LICENSE文件。

🤝 贡献

本项目由开发者为开发者打造，欢迎提交PR！贡献指南请见CONTRIBUTING.md。

版本迁移说明

如果你从v2.x迁移过来，现有的数据库完全兼容。TypeScript版本使用相同的模式和数据格式。