engram-mcp 0.1.0

The permanent and semantic memory layer for AI agents

Engram

The permanent and semantic memory layer for AI agents.

A better-notion-mcp bridge for effortless usage of Notion as a knowledge base.

Introduction

Engram transforms your Notion workspace into a living, cognitive substrate for your AI agents.

Why Engram?

According to neuropsychology, an engram is a unit of cognitive information imprinted in a physical substance, theorized to be the means by which memories are stored. This MCP server acts as that physical bridge, allowing your AI to:

• Encode Information: Instantly store facts in a local vector-like "synaptic" database.
• Stimulate Recall: Semantically search your entire knowledge base to retrieve context.
• Imprint Knowledge: Create and edit rich Notion pages (markdown, tables, mermaid) as permanent memory traces.

Features

Feature Category	Tool Name	Description	Arguments
Memory	remember_fact	Store a text snippet (memory trace) in the local synaptic database.	fact (str)
	search_memory	Semantically retrieve facts ("Stimulate Recall").	query (str)
	get_recent_memories	Retrieve the most recent memory traces.	limit (int)
Page Management	create_page	Create a new sub-page under your root page.	title (str), content (str)
	list_sub_pages	List all child pages of a specific page.	parent_id (str, optional)
	read_page_content	Read and parse the content of a page as Markdown.	page_id (str)
Content Editing	update_page	Append rich content (paragraphs, code, tables) to a page.	page_id (str), title (str), content (str), type (str), language (str)
	log_to_notion	Fast way to append a daily log/note to the root page.	title (str), content (str)
Utilities	send_alert	Send a push notification via Telegram.	message (str)

Prerequisites

Before using this tool, ensure you have Python 3.10 or higher installed.

Installing uv (Recommended)

We recommend using uv for the best experience. Download uv here

Installing pipx (Alternative)

If you prefer pipx, install it using these universal commands (works on Windows, Mac, and Linux):

# 1. Install pipx (user scope)
python3 -m pip install --user pipx

# 2. Add to PATH
python3 -m pipx ensurepath

# 3. Verify
pipx --version

Configuration

1. Notion Setup

• Integration Token: Go to Notion My Integrations -> New Integration -> Copy the "Internal Integration Secret".
• Page ID: Open the Notion page you want to use as the root. Copy the alphanumeric ID from the URL. Don't forget to connect this page to your specific integration.

2. Environment Variables

Variable	Description	Default / Note	Required
NOTION_API_KEY	Your Notion Integration Secret.	-	✅
NOTION_PAGE_ID	The ID of the root page for creating/listing content.	-	✅
TELEGRAM_BOT_TOKEN	Token from @BotFather for alerts.	Optional	❌
TELEGRAM_CHAT_ID	Your Chat ID for receiving alerts.	Optional	❌
AGENT_MEMORY_PATH	Path to the local SQLite DB.	Win: C:\Users\<User>\.engram\data\ Mac: ~/Library/.engram/data/	❌

Client Setup

Add the following to your MCP client configuration (e.g., claude_desktop_config.json for Claude Desktop).

Recommended: uv

{
  "mcpServers": {
    "engram": {
      "command": "uvx",
      "args": ["engram-mcp"],
      "env": {
        "NOTION_API_KEY": "secret_...",
        "NOTION_PAGE_ID": "page_id_...",
        "TELEGRAM_BOT_TOKEN": "bot_token_...",
        "TELEGRAM_CHAT_ID": "chat_id_...",
        "AGENT_MEMORY_PATH": "/path/to/db"
      }
    }
  }
}

Alternative: pipx

{
  "mcpServers": {
    "engram": {
      "command": "pipx",
      "args": ["run", "engram-mcp"],
      "env": {
        "NOTION_API_KEY": "secret_...",
        "NOTION_PAGE_ID": "page_id_...",
        "TELEGRAM_BOT_TOKEN": "bot_token_...",
        "...": "..."
      }
    }
  }
}

License

This project is licensed under the MIT License.