Memoria

Memoria

The Memory Your AI Lacks.

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

[](https://www.npmjs.com/package/@byronwade/memoria) [](https://opensource.org/licenses/MIT) [](https://www.typescriptlang.org/) [](https://modelcontextprotocol.io) [](https://twitter.com/byroncwade)

---

⚡ 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

| Tool | Command | |------|---------| | 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 global | npm install -g @byronwade/memoria |

🪟 Windows PowerShell Install

# 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

🍎 macOS Manual Install

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

---

📦 Claude Desktop

Config location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Option 1: Claude Code CLI (Recommended)

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

Option 2: Manual config

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

📦 Claude Code (CLI)

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

Done! Claude Code handles everything automatically.

📦 Cursor

One-liner (project-level):

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

Config locations:

• Project: .cursor/mcp.json (in project root)
• Global: ~/.cursor/mcp.json

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

📦 Windsurf

Config: ~/.codeium/windsurf/mcp_config.json

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

📦 Continue (VS Code)

Config: ~/.continue/config.json

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

📦 Cline (VS Code)

Open Cline settings → MCP Servers → Add new server:

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

📦 Other MCP Clients

Any MCP-compatible client works. Use this universal config:

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

---

CLI Commands

Memoria includes a full CLI for manual analysis - the same capabilities your AI uses:

# 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

Output Options

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

# Pipe to other tools
memoria risk src/api/route.ts --json | jq '.riskScore'

Example Output

$ 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

---

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

| Option | Default | Description | |--------|---------|-------------| | thresholds.couplingPercent | 15 | Minimum coupling % to report | | thresholds.driftDays | 7 | Days before a file is "stale" | | thresholds.analysisWindow | 50 | Number of commits to analyze | | ignore | [] | Additional glob patterns to ignore | | panicKeywords | {} | Custom keywords with severity weights | | riskWeights | {} | Override risk calculation weights |

---

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.

Documentation Coupling

Finds markdown files that reference your exported functions/types. Catches README updates needed when output format changes.

Type Coupling

Uses git pickaxe (git log -S) to find files sharing type definitions - even without direct imports.

Content Coupling

Finds files sharing string literals (error messages, constants) that should stay in sync.

Test File Coupling

Auto-discovers test files matching naming conventions (*.test.*, *.spec.*, *_test.*, etc.) and mock/fixture files - no hardcoded extensions.

Environment Variable Coupling

Finds files sharing ALL_CAPS_UNDERSCORE environment variables (API_KEY, DATABASE_URL, etc.) - works across any language.

Schema/Model Coupling

Detects database schema definitions (SQL, Prisma, TypeORM, Mongoose) and finds files that query those tables/models.

API Endpoint Coupling

Finds client code that calls API endpoints defined in route files. Catches response shape changes that break consumers.

Re-Export Chain Coupling

Detects barrel files (index.ts) that re-export your module and finds transitive importers through those barrels.

---

Example Output

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

---

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

| Flag | File | Tool | |------|------|------| | --cursor | .cursor/rules/memoria.mdc | Cursor | | --claude | .claude/CLAUDE.md | Claude Code | | --windsurf | .windsurfrules | Windsurf | | --cline | .clinerules | Cline/Continue | | --all | All of the above | All tools | | --force | Update existing rules | Overwrites Memoria section |

Smart Merge Behavior

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

| Scenario | What Happens | |----------|--------------| | File doesn't exist | Creates new file with Memoria rules | | File exists, no Memoria | Appends Memoria rules (your content preserved) | | File exists, has Memoria | Skips (use --force to update) |

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

| Metric | Value | |--------|-------| | Full analysis time | ❌ "Tool not found" or "analyze_file not available"

1. Restart your AI tool - MCP servers only load on startup
2. Check config syntax - JSON must be valid (no trailing commas)
3. Verify Node.js 18+ - Run node --version to check
4. Check file path - Config file must be in the exact location for your tool

❌ "Not a git repository"

Memoria requires a git repository with history. Make sure:

1. You're in a git repo (git status should work)
2. The repo has at least a few commits
3. You're passing an absolute path to analyze_file

❌ npx is slow or times out

Install globally for faster startup:

npm install -g @byronwade/memoria

Then update your config to use memoria directly:

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

❌ Windows path issues

Use forward slashes or escaped backslashes in paths:

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

If issues persist, install globally and use the command directly.

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

---

License

MIT

---

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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: byronwade
• Source: byronwade/memoria
• License: MIT
• Homepage: https://memoria.byronwade.com

Install and usage instructions live in the source repository linked above.