Engram MCP Server

Engram

A persistent memory server for AI agents, implemented as an MCP (Model Context Protocol) server. Stores structured notes/memories in a local SQLite database with full-text search, tagging, categorisation, TTL expiration, directional graph relationships, and full change history.

Features

• 32 MCP tools full CRUD, search, bulk ops, import/export, stats, tag utilities, graph relations, versioning
• CLI engram-cli for querying and managing memories from the terminal
• SQLite + FTS5 fast full-text search with any / all / near modes
• Graph relations link memories with typed edges (caused, references, supersedes, related)
• Change history every create/update/delete is tracked automatically; restore any previous version
• TTL optional expires_at on every memory; auto-purge on startup
• Rich filtering by category, tag, metadata key/value, date ranges, sort order
• ESLint + Prettier enforced code style
• 455 tests full coverage via Vitest (npm test)

Requirements

• Node.js 18+
• A host that supports MCP servers (VS Code with Copilot, Claude Desktop, etc.)

Installation

git clone https://github.com/Jacksini/engram-mcp.git
cd engram-mcp
npm install
npm run build

The compiled server is at build/index.js and the CLI at build/cli.js.

Configuration

VS Code (Copilot / MCP extension)

Add to your mcp.json (Ctrl+Shift+P MCP: Open User Configuration):

{
  "servers": {
    "engram-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["C:/path/to/engram-mcp/build/index.js"]
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "engram-mcp": {
      "command": "node",
      "args": ["C:/path/to/engram-mcp/build/index.js"]
    }
  }
}

Custom database path

By default the database is stored at ~/.engram/memories.db. Override it with:

"env": { "ENGRAM_DB_PATH": "C:/custom/path/memories.db" }

CLI

engram-cli lets you interact with the memory database from the terminal without needing an MCP client.

# Install globally (after npm run build)
npm link

# Or run directly
node build/cli.js <command> [options]

CLI commands

engram-cli [--db ] [--json] <command> [args] [options]

COMMANDS
  search <query>              FTS search (--limit, --mode, --category, --tag)
  list                        List memories (--category, --tag, --limit, --sort)
  get <id>                    Get a memory by UUID
  save <content>              Save a new memory (--category, --tags, --metadata, --expires)
  update <id>                 Update a memory (--content, --category, --tags, --metadata)
  delete <id> [--yes]         Delete a memory (asks for confirmation unless --yes)
  stats                       Database statistics
  backup                      Create a timestamped backup of the database
  link <from_id> <to_id>      Link two memories (--relation)
  unlink <from_id> <to_id>    Remove a link
  graph [--include-orphans]   Show memory graph (--relation, --mermaid-only)
  history <id>                Change history for a memory (--limit)
  restore <id> <history_id>   Restore a memory to a previous version
  help                        Show help

Examples

# Search and show results as JSON
engram-cli search "sqlite fts5" --limit 5 --json

# List recent code memories
engram-cli list --category code --limit 10

# Save a new memory with tags
engram-cli save "Use json_each() to query JSON arrays in SQLite" --category code --tags "sqlite,json"

# Show full memory
engram-cli get abc12345-...

# Show the memory graph as Mermaid diagram
engram-cli graph --mermaid-only

# See history of a memory and restore a version
engram-cli history abc12345-...
engram-cli restore abc12345-... 42

MCP Tools reference

Create

Common input fields:

Read