Memoria

🚀 Memoria

The Memory Your AI Lacks.

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

🚀 Quick Start

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

Then restart your AI tool. That's it!

✨ Features

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

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

Basic 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

Advanced Usage

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

📚 Documentation

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

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

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

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

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

🔧 Technical Details

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.

📄 License

MIT

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