Memory-Plus

Memory-Plus is a local, retrieval-augmented memory store for MCP agents. It lets your agent record, search, update, and visualize persistent memories such as notes, ideas, and session context across runs. Key capabilities include adding memories, retrieving by keywords or topics, fetching the most recent entries, updating or appending to existing memories, visualizing memory relationships, importing documents, and deleting entries. It also supports memory versioning so you can preserve history whenever memories are updated. To use Memory-Plus, configure the MCP server in your environment and run it via UV Runtime with the memory-plus image from npm/Yarn, or use the inspector tooling to test interactions with an MCP setup. When integrated in an MCP workflow, Memory-Plus automatically activates during relevant conversations and stores memory data for future sessions. The Google API Key environment variable is required for embedding features that rely on Gemini embeddings, and you should provide it in your environment or within your MCP settings as GOOGLE_API_KEY. You can test locally using the MCP Inspector or by running a sample agent script that interacts with memory-plus during a session.

Usage flow example:

• Add memory entries during a chat or session using your MCP integration.
• Retrieve memories by keywords or topics to inform current responses.
• Visualize memory relationships to understand context and recall behavior.
• Import documents to memory for richer recall. Update memories to append new information while preserving history.
• Use versioning to track changes to memories over time.

Prerequisites:

• Python and a functioning Python environment
• Google API Key for Gemini Embeddings (GOOGLE_API_KEY)
• UV runtime (for MCP plugin support)

Step-by-step installation:

1. Install the UV runtime (required by MCP plugins and Memory-Plus):

   • Install via pip:

     pip install uv
     

   • Or install via the provided install scripts for your OS if preferred.

2. Acquire and set up Google API Key:

   • Get your key from Google AI Studio and set it in your environment: macOS/Linux:

     export GOOGLE_API_KEY="<YOUR_API_KEY>"
     

     Windows (PowerShell):

     setx GOOGLE_API_KEY "<YOUR_API_KEY>"
     

   • If using VS Code or IDE settings, you can provide GOOGLE_API_KEY in your MCP config under env.

3. Run Memory-Plus via UV runtime:

   • Use the one-click memory-plus command in VS Code or run via CLI:

     uvx -q memory-plus@latest
     

4. Optional: Test with MCP Inspector or example agent:

   • Clone the repository and test with Inspector tools as described in the repository:

     git clone https://github.com/Yuchen20/Memory-Plus.git
     cd Memory-Plus
     npx @modelcontextprotocol/inspector fastmcp run run .\\memory_plus\\mcp.py
     

   • For an actual chat session, install dependencies and run the sample agent as shown in the README (e.g., uv run agent_memory.py) after configuring fast-agent and keys.

5. Configure MCP in your environment:

   • Create or update your MCP JSON to include the memory-plus server configuration as shown in mcp_config.

Tips and common considerations:

• Ensure GOOGLE_API_KEY is available in the environment where Memory-Plus runs; the embedding features rely on this key.
• Memory-Plus supports memory import, deletion, and versioning; use these to manage what your agent recalls.
• When running Memory-Plus in VS Code or through MCP, you can specify transportType and env variables per your IDE’s MCP settings.
• If you encounter slow first-time dependency downloads, allow some time for the initial setup; subsequent runs will be faster.
• If you modify memory data outside the MCP flow, consider re-indexing or refreshing caches if your setup uses them.
• The MCP configuration uses uvx with memory-plus@latest; you can pin a specific version if needed by replacing latest with a version tag.