@bdmarvin/mcp-server-memory

MCP Server for LLM Long-Term Memory (@bdmarvin/mcp-server-memory)

This is a Model Context Protocol (MCP) server designed to provide long-term memory capabilities for Large Language Models (LLMs). It uses a Knowledge Graph (KG) for structured data and Google Drive for larger document storage. All persistent data, including the KG itself (as JSON files), is stored in Google Drive.

This server is intended to be run as a downstream client of an MCP OAuth Controller, such as @bdmarvin/typingmind-mcp. The controller is responsible for handling Google OAuth 2.0 and injecting the necessary Google Access Tokens (__google_access_token__) which this server requires for all its operations.

Features

The server provides the following capabilities through MCP tools. All tools require a __google_access_token__ to be passed in their arguments by the controlling MCP server.

Knowledge Graph (KG) Management Tools (KG stored in Google Drive)

• Storage Strategy:
  • The Knowledge Graph for each project is stored as a single knowledge_graph.json file.
  • This JSON file resides within a project-specific folder (e.g., Project_your_project_id/) in Google Drive.
  • These project-specific folders are, in turn, located within a main base folder (default: "llm-memory-store", configurable via MCP_MEMORY_DRIVE_BASE_FOLDER_NAME) in the user's Google Drive root. The name of this base folder is configurable via the MCP_MEMORY_DRIVE_BASE_FOLDER_NAME environment variable.
• Node & Relationship Tools:
  • tool_update_kg_node: Creates or updates a node in the specified project's KG.
  • tool_add_kg_relationship: Creates a relationship between two nodes in the KG.
  • tool_delete_kg_node: Deletes a specific KG node. Important: This will also delete all relationships connected to the specified node.
  • tool_delete_kg_relationship: Deletes a specific KG relationship by its unique relationship_id.
• Specialized Tools:
  • tool_log_decision: A specialized tool to log project decisions as nodes and link them to relevant entities in the KG.
• Retrieval & Querying Tools:
  • tool_get_kg_node_details: Retrieves all information about a specific KG node, including its directly connected relationships.
  • tool_get_project_summary_from_kg: Retrieves key information, node/relationship counts, and type distributions for a given project's KG.
  • tool_search_kg: Performs a flexible search of a project's KG based on a natural language query description, entity types, and other criteria.
  • tool_retrieve_kg: Retrieves the entire Knowledge Graph (all nodes and relationships) for a specified project as a single JSON object. Warning: The response can be very large for extensive KGs.
  • tool_traverse_kg: Starts at a given node and traverses specified relationships up to a certain depth to find connected nodes. Can filter by relationship direction, types, and target node types. Useful for exploring local network structure.
  • tool_query_kg_by_attributes: Finds KG nodes based on a structured query of their attributes. Allows filtering by node type and applying multiple attribute conditions with various comparison operators (equals, contains, gt, lt, exists, in_array, etc.).

Google Drive Document Management Tools

• Storage Strategy: (Uses the same base and project folder structure in Drive as the KG files)
• Tools:
  • tool_store_document_in_project_drive:
    • Saves document content (text or bytes) to the appropriate project folder in Google Drive.
    • Creates/updates a corresponding document_reference node in the Knowledge Graph, storing drive_file_id, name, description, tags, MIME type, etc., and links it to the project.
  • tool_get_document_content_from_drive: Fetches the content of a document from Google Drive using its drive_file_id. Handles Google Docs by exporting them as plain text; other binary files may be returned as base64.
  • tool_get_document_summary_from_drive: Fetches document content from Drive and provides a basic N-character truncated summary. (Actual LLM-based summarization is a future enhancement).
  • tool_find_relevant_documents_in_kg: Queries the Knowledge Graph (searching document_reference nodes) for documents matching keywords and other metadata criteria. Returns metadata including the drive_file_id for subsequent content retrieval.

Setup and Running

1. Prerequisites:

   • Node.js (v18+ recommended).
   • An MCP OAuth Controller (like @bdmarvin/typingmind-mcp) to manage this server and provide Google Access Tokens.

2. Installation:

   git clone https://github.com/bdmarvin1/mcp-server-memory.git
   cd mcp-server-memory
   npm install

3. Configuration (Environment Variables for mcp-server-memory):

   • MCP_MEMORY_DRIVE_BASE_FOLDER_NAME (optional): Sets the name of the base folder to be created/used in the user's Google Drive root for storing all project documents and KG files.
     • Defaults to "llm-memory-store".
   • MCP_MEMORY_LOG_LEVEL (optional): Sets the logging level (e.g., 'info', 'debug', 'warn', 'error').
     • Defaults to 'info'. (Note: Currently uses console.error for logging).

4. Google Drive API Scopes (for the MCP OAuth Controller):

   • The upstream MCP OAuth Controller (@bdmarvin/typingmind-mcp) must be configured to request at least the following Google Drive API scope during user authentication:
     • https://www.googleapis.com/auth/drive.file - This allows the application to create the base folder ("llm-memory-store"), project-specific subfolders, upload files (documents and KGs) into them, and access/manage files it has created.

5. Build:

   npm run build

   (The build script tsc && shx chmod +x dist/index.js compiles TypeScript and makes the entry point executable.)

6. Running (via STDIO, typically by an MCP Controller): The MCP controller will usually run this server using a command like:

   npx @bdmarvin/mcp-server-memory

   Or by directly executing node dist/index.js if managing the process manually and providing necessary arguments/environment. The server listens for JSON-RPC 2.0 messages over STDIO. It logs its startup messages (including the Drive base folder name being used) and operational messages to stderr.

Development

• Run npm run dev for TypeScript compilation in watch mode and automatic server restart (using node --watch).
• Knowledge Graph knowledge_graph.json files are structured with nodes (object map by node_id), relationships (array), and metadata.
• Google Drive files are organized under the configured base folder, then by project-specific folders (e.g., llm-memory-store/Project_your_project_id/knowledge_graph.json).

Future Enhancements (TODO)

• Advanced KG Search: Implement more sophisticated KG traversal, filtering, and potentially NLP-based query understanding for tool_search_kg and tool_query_kg_by_attributes.
• LLM-based Document Summarization: Integrate actual LLM calls for tool_get_document_summary_from_drive.
• Transactional Updates for KG: Explore strategies for more robust KG updates, especially if multiple operations need to be atomic across different files or states.
• MIME Type Handling: More refined MIME type detection for uploads and specific content handling for various GSuite document types in getDocumentContent.
• Cross-Project Search/Queries: Potentially enable searching across multiple project KGs if feasible and required.