memoria

🚀 Memoria

为你的人工智能弥补缺失的记忆。

Memoria 是一款 MCP 服务器，它通过 Git 取证揭示隐藏的文件依赖关系，防止你的 AI 破坏代码。

🚀 快速开始

一键安装（Smithery）

点击上方徽章，通过 Smithery 一键安装 Memoria。

快速复制粘贴配置

将以下内容添加到你的 MCP 配置文件中（适用于 Claude、Cursor、Windsurf、Cline）：

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

终端单行命令

| 工具 | 命令 | |------|---------| | Claude Code | claude mcp add memoria -- npx -y @byronwade/memoria | | Claude Desktop | npx @anthropic/claude-code mcp add memoria -- npx -y @byronwade/memoria | | Cursor | mkdir -p .cursor && echo '{"mcpServers":{"memoria":{"command":"npx","args":["-y","@byronwade/memoria"]}}}' > .cursor/mcp.json | | npm 全局安装 | npm install -g @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
  }
}

| 选项 | 默认值 | 描述 | |--------|---------|-------------| | thresholds.couplingPercent | 15 | 报告的最小耦合百分比 | | thresholds.driftDays | 7 | 文件被视为“陈旧”的天数 | | thresholds.analysisWindow | 50 | 要分析的提交数量 | | ignore | [] | 要忽略的额外 glob 模式 | | panicKeywords | {} | 带有严重程度权重的自定义关键字 | | riskWeights | {} | 覆盖风险计算权重 |

自动模式

如果你希望你的 AI 在每次编辑之前自动检查 Memoria，请安装规则文件：

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

# 然后在你的项目目录中：
memoria init --all

这将安装规则文件，告诉你的 AI 在编辑代码之前始终调用 analyze_file。

安装内容

| 标志 | 文件 | 工具 | |------|------|------| | --cursor | .cursor/rules/memoria.mdc | Cursor | | --claude | .claude/CLAUDE.md | Claude Code | | --windsurf | .windsurfrules | Windsurf | | --cline | .clinerules | Cline/Continue | | --all | 以上所有 | 所有工具 | | --force | 更新现有规则 | 覆盖 Memoria 部分 |

智能合并行为

memoria init 可以安全地多次运行，它不会覆盖你现有的规则： | 场景 | 操作 | |----------|--------------| | 文件不存在 | 创建包含 Memoria 规则的新文件 | | 文件存在，但没有 Memoria 规则 | 追加 Memoria 规则（保留你的内容） | | 文件存在，且有 Memoria 规则 | 跳过（使用 --force 进行更新） |

# 首次运行 - 创建或追加
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 针对速度和最小化令牌使用进行了优化： | 指标 | 值 | |--------|-------| | 完整分析时间 | <100ms | | 每次分析的令牌数 | ~600 个令牌 | | 缓存加速 | 重复调用时加速 2000 倍以上 |

引擎分解

| 引擎 | 时间 | 用途 | |--------|------|---------| | 耦合 | ~45ms | 查找一起更改的文件 | | 波动性 | ~10ms | 计算易出错分数 | | 漂移 | <1ms | 检测陈旧依赖 | | 导入者 | ~8ms | 查找静态依赖项 | | 历史搜索 | ~7ms | 搜索 Git 提交 |

你可以自己运行基准测试：

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 帮助你避免了代码回归问题时，请告知我们。