@bdmarvin/mcp-server-memory/README.md

MCP Server for LLM Long-Term Memory using KG and Google Drive

# 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:**
    ```bash
    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:**
    ```bash
    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:
    ```bash
    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.