How It Works

Memoria combines local git forensics (free) with optional cloud memories (paid) to give your AI the intuition of a senior developer.

Two Layers of Intelligence

The Problem: Implicit Dependencies

When you ask an AI to modify a file, it can see explicit dependencies (imports, types). But real codebases have implicit dependencies:

• API routes and the frontend components that consume them
• Database schemas and the services that query them
• Config files and the modules that read them
• Test files and the implementation they verify

Static analysis can't see these connections. But git history can.

The Solution: Git Forensics (Free)

Memoria analyzes commit history to find patterns that reveal hidden dependencies. It runs thirteen analysis engines in parallel:

1. Volatility Engine

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

Panic Score = (panic_commits / total_commits) * 100

High panic score = historically bug-prone code. The AI is instructed to review changes twice and avoid removing safety checks.

2. Entanglement Engine

Analyzes the last 50 commits to find files that frequently change together:

1. For each commit that touched the target file, find all other files in that commit
2. Count how often each file appears alongside the target
3. Calculate coupling percentage: (co-changes / total) * 100
4. Return files with >15% correlation

If two files change together 85% of the time, they're coupled — even without any direct import between them.

3. Sentinel Engine

Compares modification times of coupled files:

If coupled_file.mtime < target_file.mtime - 7 days → STALE

Stale dependencies are a regression risk. The AI is instructed to verify if the coupled file needs updating.

4. Static Import Engine

Uses git grep to find files that explicitly import the target file. This works even for brand new files with no git history yet.

5. 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.

Output Format

Instead of dumping raw data, Memoria formats output to make the AI think:

🕵️ DETECTIVE WORK REQUIRED

File: dashboard/billing/page.tsx (85% coupled)
Linked via: "refactor subscription webhook schema"

Evidence (commit a3f21b4):
```typescript
+ export interface SubscriptionUpdated {
+   status: 'active' | 'canceled' | 'past_due'
+   current_period_end: number
+ }
```

> System Instruction: Analyze the code above.
> These files share the SubscriptionUpdated interface.
> Your changes MUST maintain type compatibility.

The AI sees the evidence, understands the relationship, and makes informed decisions.

Smart Filtering

Memoria automatically filters noise from coupling analysis:

• node_modules/, dist/, build/
• Lock files (package-lock.json, yarn.lock, etc.)
• Python cache (__pycache__/, *.pyc)
• Java/Rust/Go build artifacts
• Your project's .gitignore patterns

This reduces token usage by ~83% and eliminates meaningless correlations.

Performance

Memoria is optimized for speed:

• Full analysis: <100ms
• Tokens per analysis: ~600 tokens
• Cache speedup: 2000x+ on repeat calls

Results are cached with a 5-minute TTL using an LRU cache (100 items max).

Configuration

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

{
  "thresholds": {
    "couplingPercent": 20,
    "driftDays": 14,
    "analysisWindow": 100
  },
  "ignore": ["**/*.lock", "dist/", "legacy/**"],
  "panicKeywords": {
    "postmortem": 3,
    "incident": 3
  }
}

Cloud Memories (Paid)

While git forensics reveals what files are coupled, cloud memories explain why things break and how to prevent it.

How Memories Work

1. Your team saves lessons when they learn something important (e.g., “Safari OAuth requires 100ms delay”)
2. Memories are linked to files and tagged with keywords
3. When anyone on your team edits a related file, relevant memories appear automatically
4. The AI uses these memories to avoid repeating past mistakes

Memory Types

• Lesson: Something learned from a bug or incident
• Context: Background information about why code exists
• Decision: Architectural or design decisions
• Pattern: Recommended approaches for this area
• Warning: Things to avoid
• Todo: Known technical debt

Guardrails (Paid)

Guardrails are file protection rules that enforce team policies automatically.

// Example guardrails:
*.env.* → BLOCK "Environment files contain secrets"
**/auth/** → WARN "Auth code requires security review"
**/migrations/** → BLOCK "Database migrations are immutable"

When your AI tries to edit a protected file, the guardrail message appears in context, either warning the AI to be careful or blocking the change entirely.

Enabling Cloud Features

To enable cloud memories and guardrails, set these environment variables:

export MEMORIA_API_URL=https://memoria.dev
export MEMORIA_TOKEN=mem_xxxxx  # From dashboard

Without these, Memoria runs in free mode with full local git analysis. Get a team token from the Memoria dashboard.