Memoria

Memoria

AI に足りない記憶。

git のフォレンジック分析で隠れたファイル依存関係を明らかにし、AI によるコードの破損を防ぐ MCP サーバーです。

⚡ クイックインストール

ワンクリックインストール（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 は完全にお使いのマシン上で動作します。

• コードがクラウドにアップロードされることはありません
• 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
	設定 UI	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 は次の情報を返します。

• 関連ファイル - 頻繁に一緒に変更されるファイル
• リスクスコア - このコードが過去にどの程度バグを起こしやすかったか
• 古くなった依存関係 - 更新が必要な可能性のある関連ファイル
• 根拠 - ファイル同士の関連性を示す実際のコード差分

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
  }
}

仕組み

ボラティリティエンジン

コミットをスキャンし、パニックを示すキーワード（fix、bug、revert、urgent、hotfix）を、時間減衰を考慮して検出します。最近のバグほど古いバグより重視されます。また、バスファクター（誰がコードを担当しているか）も追跡します。

エンタングルメントエンジン

15%を超える頻度で一緒に変更されるファイルを検出します。インポートからは分からない暗黙の依存関係を明らかにします。

センチネルエンジン

密接に関連するファイルの同期が7日を超えてずれている場合に検出します。バグを引き起こす前に、古くなった依存関係を警告します。

静的インポートエンジン

git grepを使って、対象をインポートしているファイルを検索します。Gitの履歴がない新しいファイルも対象です。

履歴検索（考古学者）

Gitの履歴を検索して、コードがなぜ書かれたのかを理解します。見た目のおかしなコードを削除する前に、「チェスタトンの柵」問題を解決します。

ドキュメント連携

エクスポートされた関数や型を参照するMarkdownファイルを検出します。出力形式の変更時に必要なREADMEの更新を見落としません。

型連携

Gitのピックアックス（git log -S）を使って、型定義を共有するファイルを検索します。直接インポートしていないファイルも対象です。

コンテンツ連携

文字列リテラル（エラーメッセージや定数など）を共有し、同期を保つべきファイルを検出します。

テストファイル連携

命名規則（*.test.*、*.spec.*、*_test.*など）に一致するテストファイルや、モック／フィクスチャファイルを自動検出します。拡張子のハードコードは不要です。

環境変数連携

ALL_CAPS_UNDERSCORE形式の環境変数（API_KEY、DATABASE_URLなど）を共有するファイルを検出します。あらゆる言語で動作します。

スキーマ／モデル連携

データベースのスキーマ定義（SQL、Prisma、TypeORM、Mongoose）を検出し、それらのテーブル／モデルをクエリするファイルを検索します。

APIエンドポイント連携

ルートファイルで定義されたAPIエンドポイントを呼び出すクライアントコードを検出します。レスポンス形式の変更によって利用側が壊れる場合も見つけられます。

再エクスポートチェーン連携

モジュールを再エクスポートするバレルファイル（index.ts）を検出し、それらのバレル経由で間接的にインポートするファイルを検索します。

出力例

# 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

この操作では、コードを編集する前に必ずanalyze_fileを呼び出すよう、AI に指示するルールファイルがインストールされます。

インストールされる内容

スマートマージの動作

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 は高速で、トークン使用量を最小限に抑えるよう最適化されています。

エンジン別の内訳

ベンチマークを自分で実行できます。

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 — 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 がリグレッションを防いでくれたら、ぜひお知らせください。