README.md•3.86 kB
# MCP Memory Tracker
A Model Context Protocol (MCP) server that provides persistent memory capabilities using OpenAI's vector stores. This allows AI assistants to save and search through memories across conversations.
## Features
- **Save Memories**: Store text-based memories in OpenAI vector stores
- **Search Memories**: Semantic search through saved memories using natural language queries
- **Persistent Storage**: Memories are stored in OpenAI's cloud infrastructure
- **MCP Compatible**: Works with any MCP-compatible client (like Claude Desktop)
## Prerequisites
- Python 3.8+
- OpenAI API key
- UV package manager (recommended) or pip
## Installation
1. **Clone the repository**:
```bash
git clone <repository-url>
cd mcp-memory-tracker
```
2. **Install dependencies**:
```bash
# Using UV (recommended)
uv sync
# Or using pip
pip install -r requirements.txt
```
3. **Set up environment variables**:
Create a `.env` file in the project root:
```env
OPENAI_API_KEY=your_openai_api_key_here
```
## Usage
### Running the MCP Server
```bash
# Using UV
uv run server.py
# Or using Python directly
python server.py
```
### Available Tools
#### `save_memory(memory: str)`
Saves a text memory to the vector store.
**Parameters:**
- `memory` (string): The text content to save
**Returns:**
```json
{
"status": "saved",
"vector store id": "vs_xxxxx"
}
```
**Example:**
```python
save_memory("I met John at the coffee shop on Main Street. He's a software engineer who loves hiking.")
```
#### `search_memories(query: str)`
Searches through saved memories using semantic search.
**Parameters:**
- `query` (string): Natural language search query
**Returns:**
```json
{
"status": "success",
"results": ["matching memory content..."]
}
```
**Example:**
```python
search_memories("Who did I meet at the coffee shop?")
```
## Integration with MCP Clients
### Claude Desktop
Add this server to your Claude Desktop configuration:
```json
{
"mcpServers": {
"memory-tracker": {
"command": "uv",
"args": ["run", "/path/to/mcp-memory-tracker/server.py"],
"env": {
"OPENAI_API_KEY": "your_api_key_here"
}
}
}
}
```
### Other MCP Clients
This server implements the standard MCP protocol and should work with any compatible client. Refer to your client's documentation for configuration details.
## How It Works
1. **Vector Store Management**: The server automatically creates and manages an OpenAI vector store named "memories"
2. **Memory Storage**: When you save a memory, it's uploaded as a text file to the vector store
3. **Semantic Search**: The search functionality uses OpenAI's vector search capabilities to find relevant memories based on meaning, not just keywords
## Configuration
The server uses the following constants that can be modified in `server.py`:
- `VECTOR_STORE_NAME`: Name of the OpenAI vector store (default: "memories")
## Dependencies
- `fastmcp`: MCP server framework
- `openai`: OpenAI Python SDK
- `python-dotenv`: Environment variable management
## Troubleshooting
### Common Issues
1. **"OPENAI_API_KEY not found"**: Make sure your `.env` file is properly configured
2. **"'SyncPage' object has no attribute..."**: This indicates an API response structure issue - check your OpenAI SDK version
3. **File upload errors**: Ensure your OpenAI API key has vector store permissions
### Debug Mode
Add print statements to see detailed responses:
```python
print(f"Vector store ID: {vector_store.id}")
print(f"Search results: {results}")
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request
## License
[Add your license here]
## Support
For issues and questions:
- Check the [troubleshooting section](#troubleshooting)
- Review OpenAI API documentation
- Check MCP protocol documentation