engram-notion-mcp 1.2.0rc2

The permanent and semantic memory layer for AI agents

Engram Notion MCP - Semantic Memory for AI Agents

Engram Notion MCP is a powerful Model Context Protocol (MCP) server that gives your AI agents a permanent, semantic memory. It seamlessly integrates with Notion to store, retrieve, and organize information, turning your workspace into an intelligent knowledge base.

🧠 Why Engram? AI Agents often suffer from amnesia. Engram solves this by providing a persistent memory layer backed by Notion's robust database structure, combined with an interactive local SQLite memory dashboard.

---

📦 Features

Notion Integration

Feature	Tool Name	Description
Page Creation	create_page	Create new pages with content. Auto-chunks large text to avoid limits. Supports session logging.
Page Updates	update_page	Append content to existing pages. Auto-chunks large text. Supports session logging.
Logging	log_to_notion	Fast logging wrapper for appending notes/logs.
Reading	read_page_content	Read and parse page content into Agent-friendly text.
Databases	list_databases	detailed list of accessible databases.
Querying	query_database	Query databases with filters to find specific items.
Organization	list_sub_pages	List pages within a parent page.
Cleanup	delete_block	Archive/Delete blocks or pages.
Page Comments	—	Appends "last edited by {agent-name}-using-{harness}" page comments when tracking values are supplied.

Semantic Memory & Knowledge Graph (SQLite)

Feature	Tool Name	Description
Store Facts	remember_fact	Saves facts to spatial layout memory (wing/room/hall) with session tracking.
Store Relations	remember_relation	Saves relationship predicate links between concepts in the knowledge graph.
Search	search_memory	Full-text search (FTS) over stored memories.
Recall	get_recent_memories	Retrieve the latest context/facts.

Operations

Feature	Tool Name	Description
Alerts	send_alert	Send push notifications via Telegram.

---

📊 Interactive Memory Dashboard

Whenever the MCP server starts up, it automatically spins up a local web application hosted on http://localhost:3123/ (with automatic incremental port fallback if the port is in use).

Key Features:

• D3.js Force-Directed Graph: Explore your agent's structured knowledge graph showing entities and their relationships.
• Search Timeline: Real-time keyword search (FTS) through stored facts, created pages, and updates.
• Metrics Stats: Instantly track your total memories, graph nodes, graph edges, and active sessions.
• "Dream-Correction" Workspace: Edit or delete memories directly to fix hallucinations, trigger manual database compaction, and enable weekly review reminders in local storage.
• Port Reuse: If a server is already running the dashboard on the port, other newly started servers will automatically redirect to the running dashboard to avoid spawning duplicate background HTTP servers.

---

🛠 Configuration

To use Engram Notion MCP, you need to set up your environment variables.

Variable	Required	Description
NOTION_API_KEY	Yes	Your Notion Internal Integration Token (secret_...).
NOTION_PAGE_ID	No	Default Page ID for creating pages if no parent is specified.
TELEGRAM_BOT_TOKEN	No	For send_alert tool.
TELEGRAM_CHAT_ID	No	For send_alert tool.
AGENT_MEMORY_PATH	No	Custom path for the SQLite memory database.

---

💡 Quick Setup Tips

🔑 How to get Notion API Key

1. Go to Notion My Integrations.
2. Click New integration.
3. Name it (e.g., "Engram Notion MCP") and submit.
4. Copy the Internal Integration Secret. this is your NOTION_API_KEY.

🤖 How to get Telegram Bot Token & Chat ID

1. Bot Token:

   • Open Telegram and search for @BotFather.
   • Send the command /newbot.
   • Follow the prompts to name your bot.
   • Copy the HTTP API Token.

2. Chat ID:

   • Search for @userinfobot in Telegram.
   • Click Start or send /start.
   • It will reply with your Id. Copy this number.

---

Configuration Patterns

1. Minimal Setup (Flexible / Unbound)

You can omit NOTION_PAGE_ID to keep the agent "unbound". It will force the agent to ask for a destination or search for one.

"env": {
  "NOTION_API_KEY": "secret_your_key_here"
}

2. Multi-Page Support

You don't need to configure an array of IDs. Engram relies on Notion's native permissions. To give the agent access to multiple specific pages:

1. Open any page in Notion.
2. Click the ... (three dots) menu (top-right) -> Connections.
3. Look for the name you gave your integration (e.g., "Engram Notion MCP").
4. Once connected, the agent can automatically see this page using the list_accessible_pages tool.
5. Repeat this for any other page you want the agent to see.

---

🔌 Installation & Client Setup Instructions

⚡ Recommended (Fastest) - Bun

Use bunx to run the server with native performance (bun:sqlite).

Add this to your claude_desktop_config.json or mcp.json.

Config using bunx (Recommended):

{
  "mcpServers": {
    "engram-notion-mcp": {
      "command": "bunx",
      "args": ["engram-notion-mcp"],
      "env": {
        "NOTION_API_KEY": "secret_your_key_here"
      }
    }
  }
}

---

🐢 Standard - Node.js (NPX)

Works with any standard Node.js environment (better-sqlite3).

Add this to your claude_desktop_config.json or mcp.json.

Config using npx (Standard):

{
  "mcpServers": {
    "engram-notion-mcp": {
      "command": "npx",
      "args": ["-y", "engram-notion-mcp"],
      "env": {
        "NOTION_API_KEY": "secret_your_key_here"
      }
    }
  }
}

---

🐍 Alternative - Python (UVX / PIPX)

If you prefer uvx or pipx or have strict Python environments:

Add this to your claude_desktop_config.json or mcp.json.

Config using uvx (Alternative):

{
  "mcpServers": {
    "engram-notion-mcp": {
      "command": "uvx",
      "args": ["engram-notion-mcp"],
      "env": {
        "NOTION_API_KEY": "secret_your_key_here"
      }
    }
  }
}

---

Config using pipx (Alternative):

{
  "mcpServers": {
    "engram-notion-mcp": {
      "command": "pipx",
      "args": ["run", "engram-notion-mcp"],
      "env": { ... }
    }
  }
}

---

Where to put it:

• 🖥️ Desktop Apps (Claude Desktop): claude_desktop_config.json

• 🆚 VS Code / Cursor / Windsurf: User Settings (settings.json).

• Cline / Roo Code: Extension Settings -> MCP Servers.

• Kilo Code: .kilo/config.json.

• ⌨️ Gemini CLI:

  Bun (Recommended)

  gemini mcp add engram-notion-mcp bunx "engram-notion-mcp" -e NOTION_API_KEY=<your_secret_key>
  

  Node.js - NPX (Standard)

  gemini mcp add engram node "npx engram-notion-mcp" -e NOTION_API_KEY=<your_secret_key>
  

---

💬 Support & Feedback

If you face any issues or have suggestions, please feel free to:

• Open an issue on this GitHub Repository.
• Reach out to me directly via my GitHub profile.

---

Quick Links

This MCP tool is published as a package on NPM and PyPI.

• Bun / Node.js Package on NPM
• Python Package on PyPI