Sophisticated AI chatbot with long-term memory capabilities, complete Notion workspace integration, and MCP (Model Context Protocol) implementation. Features semantic, episodic, and procedural memory systems.

🧠 Agentic Long-Term Memory with Notion Integration

This project explores the concept of long-term memory in AI agents and demonstrates how to build sophisticated agentic memory systems using various approaches and tools. Now featuring complete Notion workspace integration and MCP (Model Context Protocol) implementation!

Feel free to ⭐️ the repo if it helps you understand long-term memory for agents!

πŸš€ What's New - Enhanced Features

πŸ”₯ Complete Notion Integration

  • 15+ Notion Functions: Search, read, create, update, and analyze your Notion workspace
  • Smart Content Management: Add paragraphs, headings, bullets, todos with intelligent formatting
  • Advanced Content Types: Bookmarks and internal page links with URL validation
  • Workspace Analytics: Get insights about your Notion usage patterns
  • Bulk Operations: Handle multiple pages and operations efficiently with smart pagination
  • Function Chaining: Complex multi-step workflows handled automatically
  • Production-Ready MCP Server: Complete Notion MCP Server V2.1 with bulletproof validation and comprehensive testing

🎯 MCP (Model Context Protocol) Implementation

  • Multiple Transport Support: HTTP and stdio transport protocols
  • Production Ready: Deployable MCP servers with fallback strategies
  • Tool Discovery: Automatic tool registration and discovery
  • Error Handling: Comprehensive error management and recovery

πŸ“š Comprehensive Documentation

πŸ“– Core Documentation

  • πŸ€– Complete System Explanation - Detailed walkthrough of the entire chatbot system
  • πŸ”§ How MCP Tools Work - Deep dive into MCP implementation and tool mechanics
  • πŸš€ Notion Integration Guide - Complete Notion ServerV2 integration documentation
  • πŸ”— Notion MCP Server - Complete Notion MCP Server V2.1 - Production-ready server with bulletproof validation

πŸ” Implementation Guides

  • πŸ“Š MCP Implementation Comparison - Comparison of different MCP implementation approaches
  • 🎯 MCP Notion README - Specific MCP Notion integration setup and usage
  • βš™οΈ Production Configuration - Production deployment and configuration guide

🧠 Memory System Research

πŸ“š What You'll Learn

  1. How to design a custom agentic long-term memory system
  2. How to implement long-term memory using Vector DB and Graph DB with LangChain and LangGraph
  3. How to structure memory into semantic, episodic, and procedural components
  4. Complete Notion workspace integration with natural language processing
  5. MCP (Model Context Protocol) implementation for scalable tool integration
  6. Production-ready MCP server development - see our Notion MCP Server V2.1
  7. Advanced function chaining for complex multi-step workflows
  8. Production-ready deployment strategies and configurations

πŸ’Ύ How to Run the Project

⚠️ Note: Please use Python 3.11 as Python 3.12 may cause compatibility issues with some dependencies.

1. Environment Setup

# Create virtual environment
python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows

# Install dependencies
pip install -r requirements.txt

2. Database Preparation

# Setup SQLite DB
python src/prepare_sqldb.py

# Setup Vector DB
python src/prepare_vectordb.py

# Verify databases
python src/check_sqldb.py
python src/check_vectordb.py

3. Environment Variables

# Required
export OPENAI_API_KEY="your_openai_api_key"
export NOTION_TOKEN="your_notion_integration_token"

# Optional
export NOTION_API_KEY="your_notion_integration_token"  # Alternative to NOTION_TOKEN

4. Run the Enhanced Chatbot

# Terminal version with full Notion integration
python src/chat_in_terminal.py

# Gradio UI version
python src/chat_in_ui.py

5. Test the Integration

# Test Notion integration
python test_notion_integration.py

# Test MCP functionality
python test_notion_mcp.py

🎯 Available Chatbot Versions

Version 1: Basic Chatbot (basic_chatbot_v1.py)

  • Simple conversation handling
  • Basic OpenAI integration

Version 2: Agentic Chatbot (chatbot_agentic_v2.py)

  • Function calling capabilities
  • User information management
  • Chat history search

Version 3: Enhanced Agentic Chatbot (chatbot_agentic_v3.py) - ⭐ MAIN VERSION

  • Complete Notion integration (15+ functions)
  • Advanced memory systems (Vector DB + SQL)
  • Smart function chaining
  • Production-ready architecture
  • MCP protocol support

πŸ”§ Key Features

🧠 Memory Systems

  • SQL Database: Structured user information and chat history
  • Vector Database: Semantic search through conversation history
  • Smart Summarization: Automatic conversation summarization
  • Context Management: Intelligent context preservation

πŸ”— Notion Integration

  • Search & Discovery: Full-text search across pages and databases
  • Content Management: Create, read, update pages with rich formatting
  • Advanced Content Types: Bookmarks and internal page links with validation
  • Analytics: Workspace insights and usage patterns
  • Bulk Operations: Handle multiple operations efficiently
  • Production MCP Server: Complete V2.1 Server with bulletproof validation and 48KB test suite

🎯 Function Chaining

  • Multi-step Workflows: Automatic handling of complex tasks
  • Context Awareness: Understanding when tasks require multiple steps
  • Smart Routing: Intelligent function selection and execution

βš™οΈ Production Features

  • Error Handling: Comprehensive error management
  • Fallback Systems: Multiple backup strategies
  • Scalable Architecture: Easy to extend and modify
  • MCP Protocol: Standard tool integration protocol

πŸ—οΈ Project Architecture

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚   User Interface    │───▢│  Chatbot Agentic V3  │───▢│  External Systems   β”‚
β”‚   (Terminal/UI)     β”‚    β”‚  (Main Controller)   β”‚    β”‚  (Notion, DB, etc)  β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                      β”‚
                                      β–Ό
                      β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                      β”‚           Core Components               β”‚
                      β”‚  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”  β”‚
                      β”‚  β”‚   OpenAI    β”‚  β”‚   Notion        β”‚  β”‚
                      β”‚  β”‚   Agent     β”‚  β”‚   ServerV2      β”‚  β”‚
                      β”‚  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜  β”‚
                      β”‚  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”  β”‚
                      β”‚  β”‚   Memory    β”‚  β”‚   Vector DB     β”‚  β”‚
                      β”‚  β”‚   Systems   β”‚  β”‚   (Embeddings)  β”‚  β”‚
                      β”‚  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜  β”‚
                      β”‚  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”  β”‚
                      β”‚  β”‚     MCP     β”‚  β”‚   SQL Database  β”‚  β”‚
                      β”‚  β”‚   Protocol  β”‚  β”‚   (Structured)  β”‚  β”‚
                      β”‚  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜  β”‚
                      β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

πŸ“‚ Updated Project Structure

src/
β”œβ”€β”€ chat_in_terminal.py        # Enhanced terminal chatbot
β”œβ”€β”€ chat_in_ui.py              # Gradio UI version
β”œβ”€β”€ prepare_sqldb.py           # Creates SQLite DB
β”œβ”€β”€ prepare_vectordb.py        # Creates Vector DB
β”œβ”€β”€ check_sqldb.py             # Checks SQLite DB contents
β”œβ”€β”€ check_vectordb.py          # Checks Vector DB contents
β”œβ”€β”€ notion_mcp_server/         # πŸ†• Complete Notion MCP Server
β”‚   β”œβ”€β”€ core_operations.py     # Basic Notion operations
β”‚   β”œβ”€β”€ analytics_operations.py # Workspace analytics
β”‚   β”œβ”€β”€ bulk_operations.py     # Bulk operations
β”‚   β”œβ”€β”€ update_operations.py   # Content updates
β”‚   β”œβ”€β”€ notion_utils.py        # Utility functions
β”‚   β”œβ”€β”€ api_serverV2.py        # HTTP API server
β”‚   β”œβ”€β”€ serverV2.py            # MCP server implementation
β”‚   β”œβ”€β”€ test_server.py         # πŸ†• 48KB comprehensive test suite
β”‚   └── README.md              # πŸ†• Complete MCP Server V2.1 documentation
└── utils/
    β”œβ”€β”€ basic_chatbot_v1.py    # Basic chatbot implementation
    β”œβ”€β”€ chatbot_agentic_v2.py  # Agentic chatbot v2
    β”œβ”€β”€ chatbot_agentic_v3.py  # πŸ†• Main enhanced chatbot (LATEST)
    β”œβ”€β”€ mcp_client_manager.py  # πŸ†• MCP client management
    β”œβ”€β”€ chat_history_manager.py
    β”œβ”€β”€ vector_db_manager.py
    β”œβ”€β”€ user_manager.py
    β”œβ”€β”€ prepare_system_prompt.py
    β”œβ”€β”€ search_manager.py
    β”œβ”€β”€ sql_manager.py
    β”œβ”€β”€ config.py
    └── utils.py

# Testing Files
β”œβ”€β”€ test_notion_integration.py  # πŸ†• Notion integration tests
β”œβ”€β”€ test_notion_mcp.py          # πŸ†• MCP functionality tests
β”œβ”€β”€ test_chatbot_integration.py # πŸ†• Chatbot integration tests
└── [other test files...]

# Documentation
β”œβ”€β”€ HOW_MCP_TOOLS_WORK.md      # πŸ†• MCP implementation guide
β”œβ”€β”€ NOTION_INTEGRATION_README.md # πŸ†• Notion integration docs
β”œβ”€β”€ MCP_IMPLEMENTATION_COMPARISON.md # πŸ†• Implementation comparison
β”œβ”€β”€ MCP_NOTION_README.md       # πŸ†• MCP Notion setup guide
β”œβ”€β”€ PRODUCTION_CONFIG.md       # πŸ†• Production deployment
└── README.md                  # This file

# Additional Directories
langgraph/                     # LangGraph implementations
letta/                         # Letta memory system
docker/                        # πŸ†• Docker deployment
config/                        # Configuration files
data/                          # Database storage

πŸ› οΈ Technologies Used

Core Technologies

  • Python 3.11: Main programming language
  • OpenAI API: GPT models for conversation and function calling
  • Notion API: Complete workspace integration

Memory & Database

  • SQLite: Structured data storage
  • ChromaDB: Vector database for semantic search
  • Embeddings: OpenAI text-embedding models

Integration & Protocols

  • MCP (Model Context Protocol): Standard tool integration
  • HTTP/stdio: Multiple transport protocols
  • JSON-RPC: Communication protocol

UI & Testing

  • Gradio: Web-based user interface
  • Terminal: Command-line interface
  • Comprehensive Testing: Integration and unit tests

πŸ“Š System Schemas

LLM Default BehaviorSchema 1

Concept of MemorySchema 2

Basic Chatbot SchemaSchema 3

Agentic_Chatbot_v2 SchemaSchema 4

Agentic_Chatbot_v3 Schema (Old Version)Schema 5

Longterm Memory with Graph DB and Vector DB using LangGraphSchema 6

Longterm Memory (Semantic, Episodical, and Procedural) with LangGraphSchema 7Schema 8

Old Project StructureSchema 9

πŸš€ Getting Started

  1. Read the Documentation: Start with πŸ€– Complete System Explanation
  2. Explore the MCP Server: Check out our Notion MCP Server V2.1 - production-ready with comprehensive testing
  3. Set up Environment: Follow the installation steps above
  4. Configure Notion: Set up your Notion integration token
  5. Run Tests: Verify everything works with the test files
  6. Start Chatting: Use the enhanced chatbot with natural language

🀝 Contributing

Feel free to contribute by:

  • Adding new Notion operations
  • Improving memory systems
  • Enhancing the MCP implementation
  • Adding more test cases
  • Improving documentation

πŸ“„ License

This project is open source

πŸŽ‰ This is a complete AI agent system with production-ready Notion integration, advanced memory management, and MCP protocol implementation!

MCP Server Β· Populars

MCP Server Β· New