⚡ Engram

Persistent, shared, AI-readable context layer for your codebase

Your team should never spend tokens or time re-explaining a project to an AI again.

What It Does

Engram captures your project's context once and serves it to every AI session, every teammate, every project.

• Context Persistence — SQLite knowledge graph of your codebase (symbols, relationships, module boundaries) that survives across sessions
• Shared Team Memory — Structured CLAUDE.md system that every AI session reads on startup
• Module Compression — On-demand compressed snapshots via Repomix integration
• MCP Tools — Four tools any connected AI can call proactively

Quick Start

# Initialize in your project
npx @priyanexodus/engram init

# Index your codebase
npx @priyanexodus/engram scan

# Check what was indexed
npx @priyanexodus/engram status

# Auto-configure your AI text editor
npx @priyanexodus/engram link

# Start the MCP server manually (if not linked)
npx @priyanexodus/engram serve

MCP Configuration

The easiest way to configure Engram is to use the interactive auto-linker:

npx @priyanexodus/engram link

This will automatically find your mcp.json file (for Claude Desktop, Windsurf, Cline, etc.) and inject the correct configuration.

If you prefer to configure it manually, here are the configurations for popular tools:

Claude Code / Claude.ai

Add to your MCP settings:

{
  "mcpServers": {
    "engram": {
      "command": "npx",
      "args": ["-y", "@priyanexodus/engram", "serve"],
      "cwd": "/path/to/your/project"
    }
  }
}

Antigravity / Gemini

Add this to your Antigravity MCP configuration (e.g., mcp.json or within extension settings):

{
  "mcpServers": {
    "engram": {
      "command": "npx",
      "args": ["-y", "@priyanexodus/engram", "serve"],
      "cwd": "/path/to/your/project"
    }
  }
}

Available MCP Tools

| Tool | Description | |------|-------------| | get_module_map | Compressed structural overview of any module | | find_symbol | Locate any definition or call site instantly | | get_project_memory | Read all decisions, conventions, and context | | add_project_memory | Append a decision with attribution |

CLI Commands

engram init [--template <name>]     # Initialize project (templates: base, nextjs, python-api)
engram scan [--full] [--module <p>] # Index codebase (incremental by default)
engram memory list [--category]     # List project memory entries
engram memory add <cat> <key> <val> # Add a memory entry
engram memory sync                  # Sync CLAUDE.md ↔ database
engram status                       # Show index statistics
engram link                         # Auto-configure MCP in your AI editor
engram serve                        # Start MCP server

Architecture

┌─────────────────────────────────────────────┐
│              Any AI Tool                    │
│   Claude Code · Claude.ai · Copilot · etc   │
└────────────────────┬────────────────────────┘
                     │ MCP Protocol (stdio)
┌────────────────────▼────────────────────────┐
│            Engram (Node.js)                 │
│                                             │
│  tree-sitter       →   Symbol parsing       │
│  better-sqlite3    →   Knowledge graph      │
│  repomix           →   Compression          │
│  CLAUDE.md         →   Team memory          │
└────────────────────┬────────────────────────┘
                     │
┌────────────────────▼────────────────────────┐
│           SQLite (.engram/engram.db)         │
│     symbols · edges · project_memory        │
└─────────────────────────────────────────────┘

Project Templates

base (default)

Generic project template with placeholder CLAUDE.md sections.

nextjs

Next.js App Router template with:

• App Router conventions and component patterns
• Module boundaries: app/, components/, lib/, public/

python-api

Python API template (FastAPI/Flask) with:

• API conventions and module structure
• Module boundaries: api/, models/, services/, tests/

How It Works

1. npx @priyanexodus/engram init creates the context structure (CLAUDE.md, config, .engram directory)
2. npx @priyanexodus/engram scan uses tree-sitter to parse your codebase into a SQLite knowledge graph
3. npx @priyanexodus/engram serve exposes four MCP tools that any AI can call
4. AI tools call get_project_memory on session start to load context
5. AI tools call find_symbol and get_module_map during work
6. AI tools call add_project_memory to record decisions for the team

Requirements

• Node.js ≥ 20
• For best results: C++ build tools (for tree-sitter native bindings)
  • Ubuntu/Debian: sudo apt install build-essential python3
  • macOS: xcode-select --install

Note: If tree-sitter native bindings fail to compile, Engram falls back to a regex-based parser with reduced accuracy. A clear warning will be displayed.

License

MIT © Priyadharshan Sivakumar