@mnemox/mcp-server-lite/README.md

MCP Server for MnemoX Lite - Semantic Memory for LLMs

# @mnemox/mcp-server-lite

🧠 **MCP Server for MnemoX Lite v1.1.1** - Semantic Memory for LLMs via Model Context Protocol

Connect Claude Desktop (and other MCP-compatible LLMs) to your MnemoX Lite semantic memory system with native Google Cloud vector search.## 🚀 Quick Start### 1. Run with NPX (Recommended)```bash# Interactive setup with auto-detectionnpx @mnemox/mcp-server-lite# Direct server mode  npx @mnemox/mcp-server-lite --server```

### 2. Configure Claude Desktop

The setup wizard will generate a configuration like this for your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "mnemox-lite": {
      "command": "npx",
      "args": ["mnemox-mcp-server", "--server"],
      "env": {
        "MNEMOX_API_URL": "http://localhost:3000/api/mcp",
        "MNEMOX_API_KEY": "your-api-key",
        "MNEMOX_USER_ID": "your-user-id"
      }
    }
  }
}
```

### 3. Restart Claude Desktop

After adding the configuration, restart Claude Desktop. The MCP server will start automatically when you use Claude.

## 🛠️ Available Tools

Once connected, Claude will have access to these memory tools:

### `store_information`
Store information in semantic memory for future reference.
```
store_information({
  content: "React hooks allow functional components to use state",
  tags: ["react", "hooks", "frontend"],
  source: "learning_session"
})
```

### `search_memory`
Search semantic memory for relevant information.
```
search_memory({
  query: "React hooks state management",
  maxResults: 10,
  similarityThreshold: 0.7
})
```

### `relate_information`
Find information related to a specific memory fragment.
```
relate_information({
  fragmentId: "fragment-123",
  maxResults: 10
})
```

### `contextualize_information`
Organize information into thematic contexts.
```
contextualize_information({
  query: "React development best practices",
  createIfNotExists: true,
  maxFragments: 50
})
```

### `get_memory_stats`
Get statistics about your semantic memory usage.
```
get_memory_stats()
```

## 📍 Configuration

### Environment Variables

- `MNEMOX_API_URL`: URL of your MnemoX Lite server (default: `http://localhost:3000/api/mcp`)
- `MNEMOX_API_KEY`: API key for authentication (default: `demo-key`)
- `MNEMOX_USER_ID`: User ID for memory operations (default: `demo-user`)

### Claude Desktop Config File Locations

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

## 🧪 Testing

Test the server manually:

```bash
# Start the MCP server
npx mnemox-mcp-server --server

# In another terminal, test with MCP client tools
# (Requires MCP development tools)
```

## 🔧 Development

### Local Installation

```bash
# Clone and install
git clone <repository>
cd mcp-server
npm install

# Run locally
npm start
```

### Package Structure

```
mcp-server/
├── bin/
│   └── mnemox-mcp          # NPX executable
├── src/
│   └── server.js           # MCP server implementation
├── package.json
└── README.md
```

## 🤝 Integration Examples

### Basic Memory Usage with Claude

```
Human: Remember that I prefer TypeScript over JavaScript for new projects.

Claude: I'll store that preference for you.

[Uses store_information tool]
✅ Information stored successfully!
Fragment ID: frag_abc123
Content: User prefers TypeScript over JavaScript for new projects
```

```
Human: What programming language should I use for my new web project?

Claude: Let me check your preferences first.

[Uses search_memory tool]
🔍 Found 1 relevant memory:
1. [Score: 0.85] User prefers TypeScript over JavaScript for new projects

Based on your stored preference, I recommend using TypeScript for your new web project...
```

### Context Organization

```
Human: I've been learning about React hooks. Can you organize all my React knowledge?

Claude: I'll organize your React knowledge into a context.

[Uses contextualize_information tool]
📚 Context "React development knowledge" created with 15 fragments

Your React knowledge has been organized! This includes:
- React hooks concepts
- Component patterns
- State management
- Performance optimization tips
```

## 🚨 Troubleshooting

### Common Issues

**❌ "API Error: 401 Unauthorized"**
- Check your `MNEMOX_API_KEY` in the configuration
- Ensure your MnemoX server is running and accepting the API key

**❌ "Error calling MnemoX API: fetch failed"**
- Verify your `MNEMOX_API_URL` is correct
- Check that your MnemoX server is running on the specified URL
- Try accessing the health endpoint: `curl http://localhost:3000/api/mcp/health`

**❌ "NPX package not found"**
- Ensure you have Node.js 18+ installed
- Try clearing NPX cache: `npx clear-npx-cache`

### Debug Mode

Enable verbose logging:

```bash
# Set debug environment variable
MNEMOX_DEBUG=1 npx mnemox-mcp-server --server
```

## 📚 Links

- [MnemoX Lite Documentation](https://github.com/mnemox/lite)
- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
- [Claude Desktop](https://claude.ai/desktop)

## 📄 License

MIT License - see LICENSE file for details.

---

🧠 **Built with ❤️ by the MnemoX Team**