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版本使用相同的模式和數據格式。