The Memory Your AI Lacks - MCP server giving AI Senior Developer Intuition through git forensics
npm install @byronwade/memoria
The Memory Your AI Lacks.
An MCP server that prevents your AI from breaking code by revealing hidden file dependencies through git forensics — plus cloud memories and guardrails for teams.





---
| Feature | Free (Local) | Paid (Cloud) |
|---------|--------------|--------------|
| Git Analysis (13 engines) | Unlimited | Unlimited |
| Risk Scores & Coupling | Unlimited | Unlimited |
| History Search | Unlimited | Unlimited |
| Cloud Memories | - | Team-wide context |
| Guardrails | - | File protection rules |
| Dashboard | - | Visual analytics |
Free tier runs 100% locally — no account, no API keys, no cloud.
Paid tier adds team intelligence — shared memories, guardrails, and dashboards synced across your org.
---
Click the badge above to install Memoria with one click via Smithery.
Add this to your MCP config file (works with Claude, Cursor, Windsurf, Cline):
``json`
{
"mcpServers": {
"memoria": {
"command": "npx",
"args": ["-y", "@byronwade/memoria"]
}
}
}
| Tool | Command |
|------|---------|
| Claude Code | claude mcp add memoria -- npx -y @byronwade/memoria |npx @anthropic/claude-code mcp add memoria -- npx -y @byronwade/memoria
| Claude Desktop | |mkdir -p .cursor && echo '{"mcpServers":{"memoria":{"command":"npx","args":["-y","@byronwade/memoria"]}}}' > .cursor/mcp.json
| Cursor | |npm install -g @byronwade/memoria
| npm global | |
For a Connect-button experience in Cursor, run the HTTP MCP server and register its manifest:
1) Set production env:
``
MCP_HTTP_HOST=0.0.0.0
MCP_HTTP_PORT=8799
MCP_HTTP_BASE_URL=https://your.domain.com # public HTTPS base
MEMORIA_OAUTH_CLIENT_ID=memoria-client # adjust as needed
MEMORIA_OAUTH_REDIRECT=cursor://anysphere.cursor-mcp/oauth/callback
MEMORIA_OAUTH_SECRET=replace-me # HMAC secret for JWT access tokensnpm run build && npm run start:http
2) Start the HTTP server: https://your.domain.com/manifest.json
3) In Cursor, add the MCP via manifest URL:
4) Click Connect, complete OAuth in the browser, then tools will appear.
Notes:
- OAuth code/token are issued by the built-in endpoints (/oauth/authorize, /oauth/token) with short TTLs.MEMORIA_OAUTH_SECRET
- Update and front the service with HTTPS in production.
- Replace the in-memory code/token store with durable storage for real deployments.
Windows PowerShell Install
`powershell`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
`bash`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!
---
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
---
---
To enable cloud memories and guardrails, set these environment variables:
`bash`In your shell or .env file
export MEMORIA_API_URL=https://memoria.dev
export MEMORIA_TOKEN=mem_xxxxx # Get from https://memoria.dev/dashboard
Or in your MCP config:
`json`
{
"mcpServers": {
"memoria": {
"command": "npx",
"args": ["-y", "@byronwade/memoria"],
"env": {
"MEMORIA_API_URL": "https://memoria.dev",
"MEMORIA_TOKEN": "mem_xxxxx"
}
}
}
}
Without these, Memoria runs in free mode with full local git analysis.
---
All engines run locally for free:
| Engine | What It Does | Speed |
|--------|--------------|-------|
| Volatility | Panic keyword detection with time-decay | ~10ms |
| Entanglement | Files that change together >15% | ~45ms |
| Sentinel | Drift detection for stale dependencies | <1ms |
| Static Imports | Files that import the target | ~8ms |
| History Search | Git archaeology with line-range support | ~7ms |
| Documentation | Markdown files referencing exports | ~50ms |
| Type Coupling | Files sharing type definitions | ~100ms |
| Content Coupling | Files sharing string literals | ~30ms |
| Test Files | Auto-discovered test/mock files | ~20ms |
| Environment | Files sharing env variables | ~15ms |
| Schema/Model | Database schema dependencies | ~25ms |
| API Endpoints | Client code calling your routes | ~30ms |
| Re-Export Chain | Transitive barrel file imports | ~40ms |
Total analysis time: ~150ms — all engines run in parallel.
---
Memoria includes a full CLI for manual analysis:
`bashFull forensic analysis (same as AI's analyze_file)
memoria analyze src/index.ts
---
Example Output
`
Forensics:
route.tsRISK: 65/100 - HIGH
45% volatility | 5 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---
Cloud Memories (Paid)
CRITICAL MEMORIES
- Safari OAuth requires 100ms delay before redirect (commit abc123)
- Always invalidate old sessions before creating new ones
---
Pre-flight Checklist
- [ ] Modify
route.ts
- [ ] Update billing/page.tsx (schema)
- [ ] Update tests/stripe.test.ts - stale 12d
`---
Configuration (Optional)
Create a
.memoria.json in your project root:`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
}
}
`---
Private & Local
The free tier runs 100% on your machine.
- No code is uploaded to the cloud
- No API keys required
- Works offline
- Analyzes your local
.git folder directlyYour code never leaves your computer unless you opt into cloud features.
---
Auto-Pilot Mode
Want your AI to check Memoria automatically before every edit?
`bash
Install globally first
npm install -g @byronwade/memoriaThen in your project directory:
memoria init --all
`This installs rule files that tell your AI to always call
analyze_file before editing code.| 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 |---
Requirements
- Node.js 18+
- Git repository with commit history
- MCP-compatible AI tool
---
Development
`bash
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
"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:
`bash
npm install -g @byronwade/memoria
`Then update your config to use
memoria directly:
`json
{
"mcpServers": {
"memoria": {
"command": "memoria"
}
}
}
``Still stuck? Open an issue with your config and error message.
---
MIT
---
When Memoria saves you from a regression, let us know.