shuruheel/mcp-engram

24 stars 0 forks Quality 60 Trend 32

A sophisticated knowledge graph memory system that stores interconnected information with rich semantic structure.

Overview

A Model Context Protocol (MCP) server for building and exploring a cognitive neuroscience-inspired knowledge graph. Models thought, emotion, reasoning, and episodic memory after the structure of the human mind. Backed by SQLite — zero infrastructure, single file on disk, works offline. The server stores its database at ~/.mcp-engram/knowledge.db by default. No external services required. The MCP server exposes 8 tools that let an LLM build, search, and traverse a knowledge graph: Every tool declares an input schema (validated), an output schema, and behavior annotations (read-only vs. write), and returns machine-readable structuredContent alongside a JSON text block. Writes : re-creating an existing node or edge updates the fields you provide and preserves the ones you don't. The server also exposes MCP prompts — a system prompt with the overall tool-usage workflow, plus per-tool usage guidance under each tool's name.

README

MCP Engram — Cognitive Knowledge Graph

Quick Start

npx mcp-engram

Or install globally:

npm install -g mcp-engram
mcp-engram

The server stores its database at ~/.mcp-engram/knowledge.db by default. No external services required.

Architecture

How It Works

The MCP server exposes 8 tools that let an LLM build, search, and traverse a knowledge graph:

Tool	Purpose
`search_nodes`	Full-text search across all nodes (FTS5)
`explore_context`	Weighted graph traversal around given nodes
`create_nodes`	Create or merge-update nodes of any type
`create_relations`	Create edges with context, weight, and confidence
`add_sources`	Record provenance (Source nodes + DERIVED_FROM links)
`get_temporal_sequence`	Follow chronological chains (NEXT, BEFORE, CAUSES)
`create_reasoning_chain`	Build structured multi-step reasoning
`get_reasoning_chain`	Retrieve reasoning chains by name or topic

Every tool declares an input schema (validated), an output schema, and behavior annotations (read-only vs. write), and returns machine-readable structuredContent alongside a JSON text block. Writes merge: re-creating an existing node or edge updates the fields you provide and preserves the ones you don’t.

The server also exposes MCP prompts — a system prompt with the overall tool-usage workflow, plus per-tool usage guidance under each tool’s name.

Node Types (15)

Entity, Event, Concept, Attribute, Proposition, Emotion, Agent, ScientificInsight, Law, Location, Thought, ReasoningChain, ReasoningStep, Source, EmotionalEvent

Storage

SQLite with WAL mode for concurrent reads
FTS5 virtual table for full-text search with BM25 ranking
Recursive CTEs for graph traversal
Single nodes table for all types, edges table with UNIQUE constraint, plus aliases and observations tables
Complex objects stored as JSON in a properties column

Installation

Prerequisites

Node.js v18+
A C/C++ toolchain for compiling the better-sqlite3 native module:
- Mac: Xcode Command Line Tools (xcode-select --install)
- Linux: build-essential (apt install build-essential)
- Windows: Visual Studio Build Tools

From npm

npx mcp-engram

From source

npm install
npx nx build mcp-engram
node dist/servers/mcp-engram/main.js

Environment Variables

Variable	Required	Default	Description
`MCP_ENGRAM_DB_PATH`	No	`~/.mcp-engram/knowledge.db`	Path to the SQLite database file

Integrating with Claude Desktop

Add the server to your Claude Desktop config:

Open your config file:
- Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json
Add the server configuration:

{
  "mcpServers": {
    "mcp-engram": {
      "command": "npx",
      "args": ["mcp-engram"]
    }
  }
}

Restart Claude Desktop.

Project Structure

servers/mcp-engram/          # MCP server (TypeScript, ESM)
  src/main/                  # Server bootstrap, tool handlers, prompts
  src/storage/               # SQLite backend, FTS, schema, validation
  src/types/                 # TypeScript interfaces and enums

libs/graphrag-memory/        # Shared type library (Entity, Relation, etc.)

Development

# Build all projects
npx nx run-many -t build

# Test all projects
npx nx run-many -t test

# Lint
npx nx lint mcp-engram

# Build specific project
npx nx build mcp-engram
npx nx build graphrag-memory

License

MIT

View this README on GitHub

Install

npx mcp-engram

Configuration

{
  "mcpServers": {
    "mcp-engram": {
      "command": "npx",
      "args": ["mcp-engram"]
    }
  }
}