Memoria

Memoria

你的 AI 所缺少的记忆。

一个 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 (requires 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 工具。就这么简单！

为什么选择 Memoria？

你让 AI 重构一个文件。它做得天衣无缝。你运行应用。应用崩溃了。

为什么？另一个文件依赖旧实现，但两者之间没有导入关系，因此 AI 并不知道。

**Memoria 可以解决这个问题。**它会分析 Git 历史，找出经常一起变更的文件，即使它们之间没有直接导入关系。

Without Memoria:                        With Memoria:
─────────────────                       ─────────────
You: "Update route.ts"                  You: "Update route.ts"
AI: "Done!" ✅                           Memoria: "⚠️ 85% coupled with billing.tsx"
Result: 💥 CRASH                         AI: "I'll update both files"
                                        Result: ✅ Works

隐私与本地运行

Memoria 100% 在你的机器上运行。

• 不会将代码上传到云端
• 无需 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 会返回：

• 关联文件 - 经常一起更改的文件
• 风险评分 - 此代码在历史上容易出现 Bug 的程度
• 过时依赖项 - 可能需要更新的关联文件
• 证据 - 展示文件关联原因的实际代码差异

CLI 命令

Memoria 提供完整的 CLI，供手动分析使用，功能与 AI 使用的相同：

# Full forensic analysis (same as AI's analyze_file)
memoria analyze src/index.ts

# Quick risk assessment
memoria risk src/api/route.ts

# Show coupled files
memoria coupled src/auth.ts

# Find files that import the target
memoria importers src/types.ts

# Search git history (same as AI's ask_history)
memoria history "setTimeout" src/utils.ts
memoria history "fix" --type=message

输出选项

# JSON output for scripting/CI
memoria analyze src/index.ts --json

# Pipe to other tools
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
  }
}

工作原理

Volatility 引擎

扫描提交中的恐慌关键词（fix、bug、revert、urgent、hotfix），并采用时间衰减机制——近期 Bug 比旧 Bug 更重要。还会追踪Bus Factor（由谁负责维护代码）。

Entanglement 引擎

找出同时变更的文件（发生频率超过 15%）。揭示导入关系无法展现的隐式依赖。

Sentinel 引擎

检测耦合文件是否超过 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 端点的客户端代码。捕捉可能导致使用方出错的响应结构变更。

重新导出链耦合

检测重新导出你的模块的 barrel 文件（index.ts），并通过这些 barrel 文件查找传递导入者。

输出示例

# Forensics: `route.ts`

**RISK: 65/100** — HIGH
45% volatility · 3 coupled · 8 dependents · 1 stale

> Proceed carefully. Check all coupled files and update stale dependencies.

---

## Coupled Files

**`billing/page.tsx`** — 85% (schema)
> These files share type definitions. If you modify types in one, update the other to match.
  + interface SubscriptionUpdated
  - oldStatus: string

**`route.test.ts`** — 90% [test]
> Test file for this module. Update when changing exports.

**`services/stripe.ts`** — 75% [env]
> Shares env vars: STRIPE_KEY, STRIPE_SECRET

**`README.md`** — 70% [docs]
> Documentation references: generateReport, SubscriptionStatus

**`types/billing.ts`** — 65% [type]
> Shared types: SubscriptionUpdated, PaymentStatus

**`features/billing/index.ts`** — 60% [transitive]
> Re-exports this file. Changes propagate through this barrel.

---

## Static Dependents

These files import `route.ts`. API changes require updating them.

- [ ] `src/components/SubscriptionCard.tsx`
- [ ] `src/hooks/useSubscription.ts`

---

## Pre-flight Checklist

- [ ] Modify `route.ts`
- [ ] Update `billing/page.tsx` (schema)
- [ ] Update `tests/stripe.test.ts` — stale 12d

---

## File History

**Volatile** — 45% panic score
**Expert:** Dave (90% of commits)

自动驾驶模式

希望 AI 在每次编辑前自动检查 Memoria？安装规则文件：

# Install globally first
npm install -g @byronwade/memoria

# Then in your project directory:
memoria init --all

这会安装规则文件，指示 AI 在编辑代码前始终调用 analyze_file。

安装内容

智能合并行为

memoria init 可安全地多次运行，不会覆盖现有规则：

# First run - creates or appends
memoria init --cursor
#   ✓ Created .cursor/rules/memoria.mdc

# Second run - skips (already installed)
memoria init --cursor
#   ⊘ Skipped .cursor/rules/memoria.mdc (already has Memoria rules)
#   Use --force to update existing Memoria rules.

# Force update to latest version
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 针对速度和最少 Token 用量进行了优化：

引擎细分

自行运行基准测试：

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

要求

• Node.js 18+
• 包含提交历史记录的 Git 仓库
• 兼容 MCP 的 AI 工具

Monorepo 布局（Turbo）

• apps/mcp-server — MCP 服务和 npm 包（发布 @byronwade/memoria）
• apps/api — API 后端占位项目（Node HTTP 占位符）
• apps/web — Web 前端占位项目
• packages — 共享库（未来）

开发

npm install
npm run build                     # turbo build across workspaces
npm test                          # turbo test (runs vitest in mcp-server)

# Focus on a single app/package
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"]

仍然无法解决？ 请携带配置和错误消息提交 issue。

许可证

MIT

如果 Memoria 帮你避免了一次回归，请告诉我们。