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

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

# 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

---

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 mcp add memoria -- npx -y @byronwade/memoria

Done! Claude Code handles everything automatically.

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

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

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

Config: ~/.continue/config.json

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

Open Cline settings → MCP Servers → Add new server:

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

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	<100ms
Tokens per analysis	~600 tokens
Cache speedup	2000x+ on repeat calls

Engine Breakdown

Engine	Time	Purpose
Coupling	~45ms	Find files that change together
Volatility	~10ms	Calculate bug-prone score
Drift	<1ms	Detect stale dependencies
Importers	~8ms	Find static dependents
History Search	~7ms	Search git commits

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

---

Monorepo Layout (Turbo)

• apps/mcp-server — MCP server & npm package (publishes @byronwade/memoria)
• apps/api — API backend stub (Node HTTP placeholder)
• apps/web — Web frontend stub
• packages — Shared libraries (future)

---

Development

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

---

Troubleshooting

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

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

Install globally for faster startup:

npm install -g @byronwade/memoria

Then update your config to use memoria directly:

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

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.