Memoria

🚀 Memoria

為你的人工智能彌補缺失的記憶。

Memoria 是一款 MCP 服務器，它通過 Git 取證揭示隱藏的文件依賴關係，防止你的 AI 破壞代碼。

🚀 快速開始

一鍵安裝（Smithery）

點擊上方徽章，通過 Smithery 一鍵安裝 Memoria。

快速複製粘貼配置

將以下內容添加到你的 MCP 配置文件中（適用於 Claude、Cursor、Windsurf、Cline）：

{
  "mcpServers": {
    "memoria": {
      "command": "npx",
      "args": ["-y", "@byronwade/memoria"]
    }
  }
}

終端單行命令

# Claude Desktop
$config = "$env:APPDATA\Claude\claude_desktop_config.json"
$json = if(Test-Path $config){Get-Content $config | ConvertFrom-Json}else{@{}}
$json.mcpServers = @{memoria=@{command="npx";args=@("-y","@byronwade/memoria")}}
$json | ConvertTo-Json -Depth 10 | Set-Content $config

# Claude Desktop (需要安裝 jq: brew install jq)
echo '{"mcpServers":{"memoria":{"command":"npx","args":["-y","@byronwade/memoria"]}}}' | \
  jq -s '.[0] * .[1]' ~/Library/Application\ Support/Claude/claude_desktop_config.json - > tmp.json && \
  mv tmp.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

然後重啟你的 AI 工具，就大功告成啦！

✨ 主要特性

解決文件依賴難題

當你讓 AI 重構一個文件時，它可能會完美地完成任務，但當你運行應用程序時，卻可能會崩潰。這是因為某些其他文件依賴於舊的實現，但它們之間沒有導入關係，所以 AI 並不知道。Memoria 可以通過分析 Git 歷史記錄，找到那些即使沒有直接導入也會一起更改的文件，從而解決這個問題。

隱私與本地化

Memoria 完全在你的機器上運行，無需將代碼上傳到雲端，也不需要 API 密鑰，支持離線使用，它會直接分析你本地的 .git 文件夾，確保你的代碼不會離開你的計算機。

📦 安裝指南

選擇你的 AI 工具

工具	單行命令	配置文件
	npx @anthropic/claude-code mcp add memoria -- npx -y @byronwade/memoria	見下文
	claude mcp add memoria -- npx -y @byronwade/memoria	自動配置
	mkdir -p .cursor && echo '{"mcpServers":{"memoria":{"command":"npx","args":["-y","@byronwade/memoria"]}}}' > .cursor/mcp.json	.cursor/mcp.json
	手動配置	~/.codeium/windsurf/mcp_config.json
	手動配置	~/.continue/config.json
	設置界面	Cline MCP 設置

各工具詳細安裝步驟

npx @anthropic/claude-code mcp add memoria -- npx -y @byronwade/memoria

{
  "mcpServers": {
    "memoria": {
      "command": "npx",
      "args": ["-y", "@byronwade/memoria"]
    }
  }
}

claude mcp add memoria -- npx -y @byronwade/memoria

mkdir -p .cursor && echo '{"mcpServers":{"memoria":{"command":"npx","args":["-y","@byronwade/memoria"]}}}' > .cursor/mcp.json

{
  "mcpServers": {
    "memoria": {
      "command": "npx",
      "args": ["-y", "@byronwade/memoria"]
    }
  }
}

{
  "mcpServers": {
    "memoria": {
      "command": "npx",
      "args": ["-y", "@byronwade/memoria"]
    }
  }
}

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "@byronwade/memoria"]
        }
      }
    ]
  }
}

{
  "mcpServers": {
    "memoria": {
      "command": "npx",
      "args": ["-y", "@byronwade/memoria"]
    }
  }
}

{
  "mcpServers": {
    "memoria": {
      "command": "npx",
      "args": ["-y", "@byronwade/memoria"]
    }
  }
}

⚠️ 配置完成後，請重啟你的 AI 工具。

驗證安裝

重啟後，向你的 AI 詢問：

"What MCP tools do you have available?"

你應該會在列表中看到 analyze_file 和 ask_history。

或者直接進行測試：

"Use the analyze_file tool on any file in this project"

💻 使用示例

基礎用法

在對文件進行更改之前，讓你的 AI 分析該文件：

"Analyze src/api/stripe/route.ts before I refactor it"

Memoria 會返回以下信息：

• 耦合文件 - 經常一起更改的文件
• 風險評分 - 該代碼歷史上的易出錯程度
• 陳舊依賴 - 可能需要更新的耦合文件
• 證據 - 顯示文件之間關聯的實際代碼差異

高級用法

Memoria 還提供了完整的 CLI 用於手動分析，其功能與 AI 使用的功能相同：

# 完整的取證分析（與 AI 的 analyze_file 相同）
memoria analyze src/index.ts

# 快速風險評估
memoria risk src/api/route.ts

# 顯示耦合文件
memoria coupled src/auth.ts

# 查找導入目標文件的文件
memoria importers src/types.ts

# 搜索 Git 歷史記錄（與 AI 的 ask_history 相同）
memoria history "setTimeout" src/utils.ts
memoria history "fix" --type=message

輸出選項

# 以 JSON 格式輸出，用於腳本編寫/持續集成
memoria analyze src/index.ts --json

# 管道傳輸到其他工具
memoria risk src/api/route.ts --json | jq '.riskScore'

示例輸出

$ memoria analyze src/index.ts

Forensics for `index.ts`

RISK: 45/100 (MEDIUM)
Risk factors: High volatility (38%) • Coupled (5 files) • 3 dependents

VOLATILITY
  Panic score: 38% | Commits: 24
  Top author: Dave (72%)

COUPLED FILES
  85% billing/page.tsx [schema]
      References: billing_records table. Schema changes may break queries.
  90% index.test.ts [test]
      Test file matches naming pattern. Update when changing exports.
  75% config.ts [env]
      Shares env vars: API_KEY, DATABASE_URL
  65% hooks/useData.ts [api]
      Calls endpoint: GET /api/data

STATIC DEPENDENTS
  - [ ] Check `cli.ts`
  - [ ] Check `server.ts`
  - [ ] Check `utils.ts`

Analysis completed in 142ms

📚 詳細文檔

配置（可選）

在項目根目錄下創建一個 .memoria.json 文件，以自定義閾值：

{
  "thresholds": {
    "couplingPercent": 20,
    "driftDays": 14,
    "analysisWindow": 100
  },
  "ignore": [
    "**/*.lock",
    "dist/",
    "legacy/**"
  ],
  "panicKeywords": {
    "postmortem": 3,
    "incident": 3,
    "p0": 3
  },
  "riskWeights": {
    "volatility": 0.35,
    "coupling": 0.30,
    "drift": 0.20,
    "importers": 0.15
  }
}

自動模式

如果你希望你的 AI 在每次編輯之前自動檢查 Memoria，請安裝規則文件：

# 首先全局安裝
npm install -g @byronwade/memoria

# 然後在你的項目目錄中：
memoria init --all

這將安裝規則文件，告訴你的 AI 在編輯代碼之前始終調用 analyze_file。

安裝內容

智能合併行為

memoria init 可以安全地多次運行，它不會覆蓋你現有的規則：

# 首次運行 - 創建或追加
memoria init --cursor
#   ✓ Created .cursor/rules/memoria.mdc

# 第二次運行 - 跳過（已安裝）
memoria init --cursor
#   ⊘ Skipped .cursor/rules/memoria.mdc (already has Memoria rules)
#   Use --force to update existing Memoria rules.

# 強制更新到最新版本
memoria init --cursor --force
#   ✓ Updated .cursor/rules/memoria.mdc (--force)

自動檢測

在不使用標誌的情況下運行 memoria init 將自動檢測你正在使用的工具：

memoria init
# Detected: Cursor, Claude Code
# Installing Memoria rules...
#   ✓ Created .cursor/rules/memoria.mdc
#   ✓ Appended to .claude/CLAUDE.md (preserved existing content)
# ✓ Installed/updated 2 rule file(s)

現在，Memoria 將作為每次編輯的強制安全防護。

性能

Memoria 針對速度和最小化令牌使用進行了優化：

引擎分解

你可以自己運行基準測試：

npm run build
npx tsx benchmarks/run-benchmarks.ts

要求

• Node.js 18+
• 具有提交歷史記錄的 Git 倉庫
• 兼容 MCP 的 AI 工具

單倉庫佈局（Turbo）

• apps/mcp-server — MCP 服務器和 npm 包（發佈 @byronwade/memoria）
• apps/api — API 後端存根（Node HTTP 佔位符）
• apps/web — 網頁前端存根
• packages — 共享庫（未來）

開發

npm install
npm run build                     # 跨工作區進行 turbo 構建
npm test                          # turbo 測試（在 mcp-server 中運行 vitest）

# 專注於單個應用程序/包
npx turbo run build --filter=@byronwade/memoria
npx turbo run dev --filter=@byronwade/memoria

故障排除

npm install -g @byronwade/memoria

{
  "mcpServers": {
    "memoria": {
      "command": "memoria"
    }
  }
}

"args": ["-y", "@byronwade/memoria"]

仍然遇到問題？ 提交一個問題，並提供你的配置和錯誤消息。

🔧 技術細節

波動性引擎

掃描提交記錄中的恐慌關鍵字（fix、bug、revert、urgent、hotfix），並使用時間衰減算法，即近期的 bug 比舊的 bug 更重要。同時跟蹤總線因子（誰擁有代碼）。

糾纏引擎

查找一起更改次數超過 15% 的文件，揭示導入關係無法顯示的隱式依賴關係。

哨兵引擎

檢測耦合文件是否超過 7 天不同步，在陳舊依賴導致 bug 之前標記它們。

靜態導入引擎

使用 git grep 查找導入目標文件的文件，即使是沒有 Git 歷史記錄的全新文件也能找到。

歷史搜索（考古學家）

搜索 Git 歷史記錄，以瞭解代碼編寫的原因，在你刪除看起來奇怪的代碼之前解決“切斯特頓的柵欄”問題。

文檔耦合

查找引用你導出的函數/類型的 Markdown 文件，當輸出格式更改時，捕獲需要更新的 README 文件。

類型耦合

使用 git pickaxe（git log -S）查找共享類型定義的文件，即使它們沒有直接導入關係。

內容耦合

查找共享字符串字面量（錯誤消息、常量）的文件，確保它們保持同步。

測試文件耦合

自動發現符合命名約定（*.test.*、*.spec.*、*_test.* 等）的測試文件以及模擬/夾具文件，無需硬編碼擴展名。

環境變量耦合

查找共享 ALL_CAPS_UNDERSCORE 環境變量（API_KEY、DATABASE_URL 等）的文件，適用於任何語言。

模式/模型耦合

檢測數據庫模式定義（SQL、Prisma、TypeORM、Mongoose），並查找查詢這些表/模型的文件。

API 端點耦合

查找調用路由文件中定義的 API 端點的客戶端代碼，捕獲響應形狀更改導致的消費者崩潰問題。

重新導出鏈耦合

檢測重新導出你的模塊的桶文件（index.ts），並通過這些桶文件找到傳遞性導入者。

📄 許可證

本項目採用 MIT 許可證。

當 Memoria 幫助你避免了代碼迴歸問題時，請告知我們。