Memoria

The Memory Your AI Lacks.

An MCP server that prevents your AI from breaking code by revealing hidden file dependencies through git forensics.

⚡ Quick Install

One-Click Install (Smithery)

Click the badge above to install Memoria with one click via Smithery.

Quick Copy-Paste Config

Add this to your MCP config file (works with Claude, Cursor, Windsurf, Cline):

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

Terminal One-Liners

# 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

Then restart your AI tool. That's it!

Why Memoria?

You ask your AI to refactor a file. It does a perfect job. You run your app. It crashes.

Why? Some other file depended on the old implementation - but there's no import between them, so the AI didn't know.

Memoria fixes this. It analyzes git history to find files that change together, even without direct imports.

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

Private & Local

Memoria runs 100% on your machine.

• No code is uploaded to the cloud
• No API keys required
• Works offline
• Analyzes your local .git folder directly

Your code never leaves your computer.

Installation

Choose your AI tool:

Tool	One-Liner	Config File
	npx @anthropic/claude-code mcp add memoria -- npx -y @byronwade/memoria	See below
	claude mcp add memoria -- npx -y @byronwade/memoria	Automatic
	mkdir -p .cursor && echo '{"mcpServers":{"memoria":{"command":"npx","args":["-y","@byronwade/memoria"]}}}' > .cursor/mcp.json	.cursor/mcp.json
	Manual config	~/.codeium/windsurf/mcp_config.json
	Manual config	~/.continue/config.json
	Settings UI	Cline MCP Settings

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

⚠️ After configuring, restart your AI tool.

Verify Installation

After restarting, ask your AI:

"What MCP tools do you have available?"

You should see analyze_file and ask_history in the list.

Or test directly:

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

Usage

Ask your AI to analyze a file before making changes:

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

Memoria returns:

• Coupled files - Files that frequently change together
• Risk score - How bug-prone this code is historically
• Stale dependencies - Coupled files that may need updating
• Evidence - Actual code diffs showing why files are related

Configuration (Optional)

Create a .memoria.json in your project root to customize thresholds:

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

How It Works

Volatility Engine

Scans commits for panic keywords (fix, bug, revert, urgent, hotfix) with time-decay - recent bugs matter more than old ones. Also tracks Bus Factor (who owns the code).

Entanglement Engine

Finds files that change together >15% of the time. Reveals implicit dependencies that imports can't show.

Sentinel Engine

Detects when coupled files are >7 days out of sync. Flags stale dependencies before they cause bugs.

Static Import Engine

Uses git grep to find files that import the target - even for brand new files with no git history.

History Search (The Archaeologist)

Search git history to understand why code was written. Solves the "Chesterton's Fence" problem before you delete that weird-looking code.

Example Output

### 🧠 Forensics for `route.ts`

**🔥 RISK: 65/100 (HIGH)**
> Proceed carefully. Check all coupled files and update stale dependencies.

**Risk Factors:** High volatility (45% panic score) • Tightly coupled (3 files) • Heavily imported (8 files depend on this)

---

**🔗 COUPLED FILES**

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

---

**🧱 STATIC DEPENDENTS**
> These files explicitly import `route.ts`. If you change the API, you MUST update them.
- [ ] Check `src/components/SubscriptionCard.tsx`
- [ ] Check `src/hooks/useSubscription.ts`

---

**🛑 PRE-FLIGHT CHECKLIST**
- [ ] Modify `route.ts` (primary target)
- [ ] Verify `billing/page.tsx` (schema coupling)
- [ ] Update `tests/stripe.test.ts` (stale by 12 days)

---

**📊 VOLATILITY**
**🔥 Status:** VOLATILE (Score: 45%)
**Expert:** Dave wrote 90% of this file. If the logic is unclear, assume it is complex.

Auto-Pilot Mode

Want your AI to check Memoria automatically before every edit? Install the rule files:

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

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

This installs rule files that tell your AI to always call analyze_file before editing code.

What Gets Installed

Smart Merge Behavior

memoria init is safe to run multiple times - it won't overwrite your existing rules:

# 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)

Auto-Detection

Running memoria init without flags will auto-detect which tools you're using:

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)

Now Memoria acts as a mandatory safety guard for every edit.

Performance

Memoria is optimized for speed and minimal token usage:

Engine Breakdown

Run benchmarks yourself:

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

Requirements

• Node.js 18+
• Git repository with commit history
• MCP-compatible AI tool

Development

npm install
npm run build
npm test        # 294 tests

Troubleshooting

npm install -g @byronwade/memoria

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

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

Still stuck? Open an issue with your config and error message.

License

MIT

When Memoria saves you from a regression, let us know.