Engram MCP Server

Engram

The "Missing Context" Engine for AI Agents.

Engram gives your AI agent the context it can’t see in the code alone.

While LLMs are excellent at analyzing the specific files you give them, they lack the broader context of your repository's history and guardrails. Engram bridges this gap by surfacing hidden dependencies (via git history) and required behaviours (via test intents) that the AI would otherwise not have access to, miss or ignore.

Why Engram?

• Temporal History: Answers "What usually changes when this file changes?" to prevent the "fix one thing, break another" cycle.
• Test Intent: Extracts test intent strings (e.g., "should handle negative balance") so the AI understands what behaviour to preserve.
• Organizational Memory: A persistent store for you or the LLM to record undocumented architectural constraints, ensuring lessons learned aren't lost when you start a new conversation.

Built for Privacy. Public for Integrity.

• Local-First: All processing happens on your local hardware.
• Zero Telemetry: We do not track your usage, your code, or your identity.
• Audit it yourself: The source code is available below.

Real-World Example: The Bug That Tests Can't Catch

A TypeScript service (TransactionExportService) writes pipe-delimited lines like TXN-001|2024-11-15|250.00|COMPLETED.

A legacy JavaScript cron job (legacy-mainframe-sync.js) parses them using hardcoded array indices - parts[2] for amount, parts[3] for status.

There are zero imports between them. No shared types. Nothing in the code connects them.

The task: "Add a currency field next to the amount."

Without Engram

The AI agent updates the TypeScript service and tests. The export format becomes ID|DATE|AMOUNT|CURRENCY|STATUS. All tests pass. The PR ships.

The problem: The legacy script still reads parts[3] expecting a status like COMPLETED - but now gets USD. parseFloat("USD") returns NaN. The mainframe receives corrupted data. Nothing failed. Nothing warned. Silent breakage in production.

With Engram

Before writing any code, the agent calls get_impact_analysis. Engram checks git history and returns:

Critical Risk (0.99): bin/legacy-mainframe-sync.js — Changed together in 21 of 21 commits (100%)

The agent reads the flagged file, finds the positional parser, and updates both files together. Same feature, zero breakage.

After the fix, the agent calls save_project_note:

"The export line format is consumed by bin/legacy-mainframe-sync.js using hardcoded positional indices. Any change to field order MUST be mirrored there. Current format: ID|DATE|AMOUNT|CURRENCY|STATUS (indices 0-4)."

Now every future agent gets this warning automatically - before it writes a single line of code.

What It Does

1. Temporal Graph

• What: Mines git history to find files that are frequently committed alongside your target file.
• Why: To reveal hidden dependencies. If A.ts and B.ts changed together 40 times in the last year, your AI needs to know about B.ts before editing A.ts.

2. Validation Graph

• What: Automatically locates relevant tests and extracts their specific intent strings (e.g., it("should validate JWT expiration")).
• Why: To provide behavioural guardrails. The AI can check its plan against your existing test requirements without needing to read the full test suite.
• Supported Frameworks:
  • JS/TS: Vitest, Jest, Mocha, Playwright, Cypress (it, test, describe)
  • JVM (Java/Kotlin/Scala): JUnit 4, JUnit 5 (@DisplayName), Kotest, ScalaTest
  • Rust: Native #[test]
  • Python: Pytest, Unittest (def test_...)
  • Go: Native func Test...

3. Knowledge Graph

• What: A persistent store where the LLM can save/retrieve "memories" about architectural decisions, edge cases, or project quirks.
• Why: To bridge the gap between sessions. If the AI learns that "Auth requires a restart on config change," it saves that note so the next AI agent knows it too.

Tool calls

1. `get_impact_analysis` - Blast radius calculation for a target file

For a given file, return the impacted files, their test intents and any stored notes.

Example:

{
  "file_path": "src/Auth.ts",
  "repo_root": "/path/to/repo"
}

Returns:

{
  "summary": "Changing src/Auth.ts may affect 2 files. 1 critical risk, 1 medium risk.\n\n⚠️ Critical Risk (0.89): src/Session.ts\n   Changed together in 48 of 50 commits (96%)\n   Notes: Session requires Redis connection\n\n⚠ High Risk (0.72): src/Auth.test.ts\n   Changed together in 31 of 50 commits (62%)\n   Current test behaviour (may need updating):\n     - should login with valid credentials\n     - should reject invalid password\n     - should handle OAuth callback",
  "formatted_files": [
    {
      "path": "src/Session.ts",