memofai-mcp-server/README.md

Model Context Protocol (MCP) server for Memory-of-Agents - Enables LLMs to manage AI memory, workspaces, and bots

# Memory-of-Agents MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/MCP-Compatible-blue.svg)](https://modelcontextprotocol.io)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7+-blue.svg)](https://www.typescriptlang.org/)

A production-ready [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that enables Large Language Models to manage AI memory, workspaces, and bots through the [Memory-of-Agents](https://memof.ai) API.

## 🎯 What is This?

This MCP server acts as a bridge between LLMs (like Claude, GPT-4, etc.) and the Memory-of-Agents platform, allowing AI assistants to:

- **📁 Manage Workspaces** - Create and organize AI agent environments
- **🤖 Configure Bots** - Set up specialized AI agents with different capabilities
- **🧠 Store & Retrieve Memories** - Enable persistent context and knowledge across conversations
- **🔍 Semantic Search** - Find relevant information using natural language queries

## 🚀 Quick Start

### Prerequisites

- Node.js 18 or higher
- A Memory-of-Agents API token ([Get one here](https://dashboard.memof.ai/access-tokens))

### Installation

```bash
# Clone or download this repository
git clone https://github.com/memof-ai/memofai-mcp-server.git
cd mcp-server

# Install dependencies
npm install

# Build the server
npm run build
```

### Configuration

Set your API token as an environment variable:

```bash
export MEMOFAI_API_TOKEN="moa_your_token_here"

# Optional: Set environment (default is production)
export MEMOFAI_ENVIRONMENT="production"  # or: dev, alpha, beta, sandbox
```

### Testing with MCP Inspector

The easiest way to test and interact with the server:

```bash
npm run inspector
```

This opens an interactive inspector where you can:
- See all available tools
- Test tool executions
- View request/response data
- Debug issues

### Integration with Claude Desktop

Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "memofai": {
      "command": "npx",
      "args": ["memofai-mcp-server"],
      "env": {
        "MEMOFAI_API_TOKEN": "moa_your_token_here",
        "MEMOFAI_ENVIRONMENT": "production"
      }
    }
  }
}
```

### Integration with Other MCP Clients

This server uses stdio transport and can integrate with any MCP-compatible client:

```javascript
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: 'npx',
  args: ['memofai-mcp-server'],
  env: {
    MEMOFAI_API_TOKEN: 'moa_your_token',
  }
});

const client = new Client({ name: 'my-client', version: '1.0.0' }, { capabilities: {} });
await client.connect(transport);
```

## 📚 Available Tools

### Workspace Management

#### `list_workspaces`
List all workspaces for the authenticated user.

**Use Case:** Discover available workspaces before creating bots.

**Example:**
```json
{}
```

#### `create_workspace`
Create a new workspace for organizing bots.

**Parameters:**
- `name` (string, required): Name of the workspace (1-200 chars)
- `description` (string, optional): Description (max 500 chars)

**Example:**
```json
{
  "name": "Customer Support AI",
  "description": "Workspace for customer support chatbots"
}
```

#### `get_workspace`
Retrieve detailed information about a specific workspace.

**Parameters:**
- `workspace_id` (string, required): UUID of the workspace

**Example:**
```json
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

#### `update_workspace`
Update an existing workspace's name or description.

**Parameters:**
- `workspace_id` (string, required): UUID of the workspace
- `name` (string, optional): New name
- `description` (string, optional): New description

**Example:**
```json
{
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Updated Workspace Name"
}
```

#### `delete_workspace`
Delete a workspace. **WARNING:** This also deletes all associated bots and memories.

**Parameters:**
- `workspace_id` (string, required): UUID of the workspace

### Bot Management

#### `list_bots`
List all bots for the authenticated user.

**Use Case:** Discover available bots before storing or searching memories.

**Example:**
```json
{}
```

#### `create_bot`
Create a new bot within a workspace.

**Parameters:**
- `name` (string, required): Name of the bot (1-200 chars)
- `workspace_id` (string, required): UUID of the workspace
- `description` (string, optional): Description (max 500 chars)
- `type` (string, optional): Bot type - one of:
  - `conversational` (default) - For chat interactions
  - `knowledge_base` - For Q&A systems
  - `task_oriented` - For specific tasks
  - `analytical` - For data analysis
  - `creative` - For content generation

**Example:**
```json
{
  "name": "Customer Support Bot",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "description": "Handles customer inquiries",
  "type": "conversational"
}
```

#### `get_bot`
Retrieve detailed information about a specific bot.

**Parameters:**
- `bot_id` (string, required): UUID of the bot

#### `update_bot`
Update an existing bot's configuration.

**Parameters:**
- `bot_id` (string, required): UUID of the bot
- `name` (string, optional): New name
- `description` (string, optional): New description
- `type` (string, optional): New bot type
- `is_active` (boolean, optional): Active status

#### `delete_bot`
Delete a bot. **WARNING:** This also deletes all associated memories.

**Parameters:**
- `bot_id` (string, required): UUID of the bot

### Memory Management

#### `store_memory`
Store a new memory for a bot.

**Parameters:**
- `bot_id` (string, required): UUID of the bot
- `content_text` (string, required): The memory content
- `memory_type` (string, optional): Type of memory
  - `fact` - Factual information
  - `preference` - User preferences
  - `credential` - Access credentials
  - `event` - Events or occurrences
  - `task` - Tasks or to-dos
  - `other` (default) - General information
- `source_type` (string, optional): Source (e.g., "api", "mcp")
- `user_note` (string, optional): Note about this memory
- `importance_score` (number, optional): 0-1, default 0.5
- `permanence_level` (string, optional): Retention policy
  - `ephemeral` - Temporary
  - `session` - Current session
  - `permanent` (default) - Long-term
- `privacy_level` (string, optional): Access control
  - `private` (default) - Owner only
  - `team` - Team access
  - `public` - Public access

**Example:**
```json
{
  "bot_id": "123e4567-e89b-12d3-a456-426614174000",
  "content_text": "User prefers technical explanations with code examples",
  "memory_type": "preference",
  "importance_score": 0.8,
  "permanence_level": "permanent"
}
```

#### `search_memories`
Search bot memories using natural language (semantic search).

**Parameters:**
- `bot_id` (string, required): UUID of the bot
- `query` (string, required): Natural language search query
- `top_k` (number, optional): Number of results (1-100, default 10)
- `generate_answer` (boolean, optional): Generate answer from memories (default false)

**Example:**
```json
{
  "bot_id": "123e4567-e89b-12d3-a456-426614174000",
  "query": "What are the user's communication preferences?",
  "top_k": 5,
  "generate_answer": true
}
```

#### `list_memories`
List memories for a bot with filtering and pagination.

**Parameters:**
- `bot_id` (string, required): UUID of the bot
- `memory_type` (string, optional): Filter by type
- `limit` (number, optional): Max results (1-100, default 20)
- `offset` (number, optional): Skip count for pagination (default 0)

**Example:**
```json
{
  "bot_id": "123e4567-e89b-12d3-a456-426614174000",
  "memory_type": "preference",
  "limit": 50
}
```

#### `delete_memory`
Delete a specific memory by ID.

**Parameters:**
- `memory_id` (string, required): UUID of the memory

#### `reprocess_memory`
Reprocess a memory to update embeddings, summary, or entities.

**Parameters:**
- `memory_id` (string, required): UUID of the memory

## 🎓 LLM Usage Patterns & Best Practices

### For AI Assistants Using This MCP Server

When you (the AI assistant) have access to this MCP server, follow these patterns for optimal results:

#### 1. **Setup Workflow**

Always establish context before performing memory operations:

```
1. List available workspaces → Check if user has workspaces
2. If no workspace: Create one first
3. List bots in the workspace → Check if relevant bot exists
4. If no bot: Create appropriate bot type
5. Now ready for memory operations
```

#### 2. **Memory Storage Strategy**

**DO:**
- Store distinct, atomic pieces of information
- Use appropriate `memory_type` for categorization
- Set `importance_score` based on relevance (user preferences: 0.7-0.9, casual facts: 0.3-0.5)
- Use `permanence_level`: permanent for user preferences, session for temporary context

**DON'T:**
- Store entire conversations as single memories
- Mix multiple unrelated facts in one memory
- Store trivial, transient information as permanent

**Example - Good Memory Storage:**
```
User says: "I'm a software engineer working on Python projects, and I prefer detailed explanations."

Store as 2 separate memories:
1. "User is a software engineer working primarily with Python"
   - memory_type: "fact"
   - importance_score: 0.8
   
2. "User prefers detailed, thorough explanations"
   - memory_type: "preference"
   - importance_score: 0.9
```

#### 3. **Search Strategy**

**When to search:**
- At conversation start (retrieve user context)
- When user asks questions that might relate to past interactions
- Before making recommendations based on preferences
- When uncertain about user preferences

**Search query tips:**
- Use natural language that captures intent
- Be specific about what you're looking for
- Use `generate_answer: true` when you want synthesized information

**Example:**
```
User: "What kind of projects was I working on?"

Search query: "user's current projects and work"
With: generate_answer: true, top_k: 5
```

#### 4. **Workspace & Bot Organization**

**Workspace naming conventions:**
- Purpose-based: "Customer Support", "Personal Assistant"
- Project-based: "Project Apollo", "Marketing Campaign"
- User-based: "John's AI Workspace"

**Bot type selection:**
- `conversational`: General chat, customer support
- `knowledge_base`: Documentation Q&A, FAQ bots
- `task_oriented`: Appointment booking, task management
- `analytical`: Data analysis, report generation
- `creative`: Content creation, brainstorming

#### 5. **Error Handling**

When operations fail:
1. Check the error message for specifics
2. Verify IDs are valid UUIDs
3. Ensure workspace exists before creating bots
4. Ensure bot exists before memory operations
5. Inform user clearly about the issue

#### 6. **Privacy & Security**

- Default to `privacy_level: "private"` unless user specifies sharing
- Use `permanence_level: "ephemeral"` for sensitive information
- Never store credentials as plain text (use `memory_type: "credential"` and ensure encryption)

### Example Conversation Flow

```
User: "Remember that I prefer Python over JavaScript"

AI Assistant:
1. Check if workspace exists (list_workspaces)
2. Check if bot exists (list_bots)
3. Store memory:
   {
     "bot_id": "...",
     "content_text": "User prefers Python programming language over JavaScript",
     "memory_type": "preference",
     "importance_score": 0.85,
     "permanence_level": "permanent",
     "privacy_level": "private"
   }
4. Respond: "I've remembered your preference for Python over JavaScript."

Later conversation:
User: "What languages do I like?"

AI Assistant:
1. Search memories:
   {
     "bot_id": "...",
     "query": "programming language preferences",
     "top_k": 5,
     "generate_answer": true
   }
2. Use results to respond with personalized answer
```

## 🛠️ Development

### Project Structure

```
mcp-server/
├── src/
│   └── index.ts          # Main MCP server implementation
├── build/                # Compiled JavaScript (generated)
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── README.md            # This file
├── LICENSE              # MIT License
└── CHANGELOG.md         # Version history
```

### Building

```bash
npm run build
```

### Development with Watch Mode

```bash
npm run watch
```

### Testing Changes

```bash
# After making changes
npm run build
npm run inspector
```

## Documentation

For detailed information, see the `/docs` folder:

- **[Tool Reference](docs/TOOLS.md)** - Complete guide to all 15 available tools
- **[Architecture](docs/ARCHITECTURE.md)** - System design and technical architecture
- **[LLM Prompts](docs/LLM_PROMPTS.md)** - Optimal prompts and usage patterns for LLMs

## Security

- API tokens are passed via environment variables (not hardcoded)
- All communication uses HTTPS (when not in dev mode)
- Memories default to private access level
- UUIDs are validated before API calls

## 📝 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🤝 Contributing

Contributions are welcome! This is an open-source project under the MIT license.

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📞 Support

- **Documentation:** [https://docs.memof.ai](https://docs.memof.ai)
- **Issues:** [GitHub Issues](https://github.com/memof-ai/memofai-mcp-server/issues)
- **Email:** dev@memof.ai
- **Discord:** [Join our community](https://discord.gg/memofai)

## 🔗 Related Projects

- [memofai JavaScript SDK](https://github.com/memof-ai/memofai-js-sdk)
- [memofai Python SDK](https://github.com/memof-ai/memofai-python-sdk)
- [Model Context Protocol](https://modelcontextprotocol.io)

## 🙏 Acknowledgments

- Built on the [Model Context Protocol](https://modelcontextprotocol.io) by Anthropic
- Powered by [Memory-of-Agents](https://memof.ai) infrastructure
- Uses the [memofai JavaScript SDK](https://www.npmjs.com/package/memofai)

---

**Made with ❤️ by the Memory-of-Agents team**