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.

- 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 whatbehaviourto 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 likeTXN-001|2024-11-15|250.00|COMPLETED.

A legacy JavaScript cron job (legacy-mainframe-sync.js) parses them usinghardcoded 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 acurrencyfield next to the amount."

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

The problem:The legacy script still readsparts[3]expecting a status likeCOMPLETED- but now getsUSD.parseFloat("USD")returnsNaN. The mainframe receives corrupted data. Nothing failed. Nothing warned. Silent breakage in production.

Before writing any code, the agent callsget_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 updatesbothfiles together. Same feature, zero breakage.

After the fix, the agent callssave_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:Mines git history to find files that are frequently committed alongside your target file.
- Why:To reveal hidden dependencies. IfA.tsandB.tschanged together 40 times in the last year, your AI needs to know aboutB.tsbefore editingA.ts.

- 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:Nativefunc Test...

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

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.

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

{ "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", "risk_level": "Critical", "risk_score": 0.89, "description": "Changed together in 48 of 50 commits (96%)", "memories": ["Session requires Redis connection"] }, { "path": "src/Auth.test.ts", "risk_level": "High", "risk_score": 0.72, "description": "Changed together in 31 of 50 commits (62%)", "test_intents": [ "should login with valid credentials", "should reject invalid password", "should handle OAuth callback" ] } ], "coupled_files": [...], "commit_count": 50 }

2.save_project_note- Remember context about files

Store persistent notes that automatically appear in future impact analyses.

{ "file_path": "src/Auth.ts", "note": "Uses JWT tokens, must validate expiry timestamp", "repo_root": "/path/to/repo" }

3.read_project_notes- Retrieve saved context

Search notes by content or file path, or list all project knowledge.

{ "query": "Redis", "repo_root": "/path/to/repo" }

Engram is built to be invisible until you need it. It uses anAdaptive Indexing Strategythat respects your CPU and scales from side-projects to massive monorepos.

We take performance seriously. Engram is benchmarked against theLinux Kernelrepository (1.2 million+ commits).

┌─────────────┐ │ AI Agent │ ← MCP protocol over stdio └──────┬──────┘ │ ┌──────▼──────────────┐ │ Node.js Adapter │ ← TypeScript MCP server │ (adapter/) │ └──────┬──────────────┘ │ spawns & communicates via JSON ┌──────▼──────────────┐ │ Rust Core Binary │ ← Fast git indexing + SQLite │ (core/) │ └──────┬──────────────┘ │ reads ┌──────▼──────────────┐ │ .engram/engram.db │ ← Persistent SQLite database └─────────────────────┘

Engram is anMCP serverand works with any MCP-compatible client.

claude mcp add --scope user --transport stdio engram -- npx -y @spectra-g/engram-adapter

## Engram Workflow Policy You have access to a tool called engram (specifically get_impact_analysis and save_project_note). You MUST follow this strictly sequential workflow for EVERY code modification request: ### Phase 1: Analysis (MANDATORY START) 1. Blast Radius Check: Before reading code or proposing changes, you MUST call get_impact_analysis on the target file(s). 2. Context Loading:  Coupling: If "High" or "Critical" risk files are returned, evaluate if they are functionally related.  Action: Read the file (read_file) if it poses a logical regression risk.  Ignore: Skip files that appear coincidental (e.g., lockfiles, gitignore, bulk formatting updates).  Memories: Pay close attention to any "Memories" returned in the analysis summary.  Tests: If test_intents are present, treat them as strict behavioural constraints. If absent, proceed with standard code analysis. ### Phase 2: Execution 3. Fix/Refactor: Proceed with the code changes. Update tests if the behaviour is intentionally changing. ### Phase 3: Knowledge Capture (MANDATORY END) 4. Save Learnings: Before finishing, ask: "Would a future developer be surprised by something I discovered?"  IF YES (Hidden dependencies, non-obvious bugs, env quirks): You MUST use save_project_note. * IF NO (Typos, standard refactors, documented behaviour): Do NOT save a note.

npm run build:all # Build Rust core + TypeScript adapter npm run test:all # Run standard test suite

# 1. Clone linux kernel to ../linux # 2. Run the ignored performance tests npm run test:all-local

View License|Purchase Commercial License

Fast semantic code search for AI agents — find symbols, references, and callers across any codebase. Pre-built index committed to git, instant queries via MCP.