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 <path>] [--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

list_memories / search_memories common filters

search_memories extra parameters

get_context_snapshot parameters

Update

Delete

Graph relations

Memories can be linked with directional, typed edges forming a queryable graph.

Relation types

get_graph parameters

Example output:

{
  "node_count": 3,
  "edge_count": 2,
  "nodes": [...],
  "edges": [...],
  "mermaid": "flowchart LR\n  nabcd1234[\"Memory A (code)\"] -- caused --> nef567890[\"Memory B (decision)\"]"
}

Change history & restore

Every memory change (create, update, delete) is automatically recorded in the memory_history table via SQLite triggers.

get_history parameters

Example entry:

{
  "history_id": 42,
  "memory_id": "...",
  "operation": "update",
  "content": "Previous content",
  "category": "code",
  "tags": ["sqlite"],
  "metadata": {},
  "expires_at": null,
  "changed_at": "2026-02-28 02:00:00"
}

restore_memory parameters

Note: The restore is tracked as a new update entry in history. Deleted memories cannot be restored this way recreate them from get_history data using save_memory.

Import / Export

Stats & Maintenance

Auto-purge: expired memories are removed automatically on every server startup.

Tag utilities

Categories

Development

npm run build          # compile TypeScript  build/
npm run build:watch    # watch mode
npm run typecheck      # type-check only (no emit)
npm test               # run all 455 tests
npm run test:watch     # interactive watch mode
npm run lint           # ESLint
npm run lint:fix       # ESLint with auto-fix
npm run format         # Prettier
npm run format:check   # Prettier check (CI-friendly)

Project structure

src/
  index.ts              # MCP server entry point
  cli.ts                # CLI entry point (engram-cli)
  db/
    database.ts         # MemoryDatabase class (all SQL logic)
    schema.ts           # SQLite DDL + triggers + migrations
  tools/                # One file per MCP tool (32 total)
  types/
    memory.ts           # All TypeScript interfaces and types
tests/
  db/
    database.test.ts    # DB-layer unit tests
  tools/                # Tool-layer tests (one file per tool)
  helpers/
    test-db.ts          # createTestDb()  in-memory DB factory
build/                  # Compiled output (git-ignored)

Schema migrations

Environment variables

License

ISC