# Mem0 Agent Memory
[](https://pypi.org/project/mem0-agent-memory/)
[](https://pepy.tech/projects/mem0-agent-memory)
[](https://pypi.org/project/mem0-agent-memory/)
[](https://pypi.org/project/mem0-agent-memory/)
[](https://opensource.org/licenses/MIT)
MCP server for Mem0 agent memory management with multi-backend support.
## Features
- **Multi-backend**: FAISS (local), OpenSearch (AWS), Mem0 Platform (cloud)
- **AWS Bedrock integration**: Uses Amazon Titan embeddings and Claude 3.5 Haiku for processing
- **Auto user detection**: Uses system username when no user_id provided
- **Relevance filtering**: Returns memories with score > 0.7
- **Complete memory operations**: store, search, list, get, delete, history
- **Pagination support**: Handle large memory collections efficiently
- **Recent memory tracking**: Get latest updates for session continuity
- **Robust error handling**: Graceful fallbacks and clear error messages
## Installation
```bash
pip install mem0-agent-memory
```
## Quick Start
```bash
# Run directly with uvx
uvx mem0-agent-memory
# Or install and run
pip install mem0-agent-memory
python -m mem0_agent_memory
```
## Configuration
### AWS Configuration
For AWS Bedrock integration (used by default), ensure AWS credentials are configured:
```bash
# Option 1: AWS CLI configuration
aws configure
# Option 2: Environment variables
export AWS_ACCESS_KEY_ID="your-access-key"
export AWS_SECRET_ACCESS_KEY="your-secret-key"
export AWS_REGION="us-west-2"
```
### Environment Variables
```bash
# FAISS (default - uses .mem0/memory in current directory)
export FAISS_PATH="/path/to/memory/storage" # Optional
# OpenSearch
export OPENSEARCH_HOST="your-opensearch-endpoint"
export AWS_REGION="us-west-2"
# Mem0 Platform
export MEM0_API_KEY="your-api-key"
# User/Agent ID (optional - auto-detects if not provided)
export MEM0_USER_ID="custom-user-id" # Defaults to system username
export MEM0_AGENT_ID="custom-agent-id" # Defaults to workspace name
```
### MCP Client Setup
#### Amazon Q CLI
Create or edit the MCP configuration file:
**Global Scope:** `~/.aws/amazonq/mcp.json`
**Local Scope:** `.amazonq/mcp.json` (project-specific)
```json
{
"mcpServers": {
"mem0-agent-memory": {
"command": "uvx",
"args": ["mem0-agent-memory"],
"env": {
"FAISS_PATH": "/Users/yourname/.mem0/agent",
"MEM0_USER_ID": "john",
"MEM0_AGENT_ID": "my-project"
}
}
}
}
```
#### KIRO
Add to your KIRO MCP configuration:
```json
{
"mcpServers": {
"mem0-agent-memory": {
"command": "uvx",
"args": ["mem0-agent-memory"],
"env": {
"FAISS_PATH": "/Users/yourname/.mem0/agent",
"MEM0_USER_ID": "john",
"MEM0_AGENT_ID": "my-project"
}
}
}
}
```
**Agent Steering:** Use the content from [`docs/KIRO_AGENT_STEERING.md`](docs/KIRO_AGENT_STEERING.md) as your agent steering document to enable memory-first development workflows.
## Tools
- `store_memory(content, user_id?, agent_id?, metadata?)` - Store memory with metadata
- `search_memories(query, user_id?, agent_id?, limit?, page?, page_size?)` - Search with relevance filtering & pagination
- `list_memories(user_id?, agent_id?, page?, page_size?)` - List all memories with pagination
- `get_memory(memory_id)` - Get specific memory by ID
- `delete_memory(memory_id)` - Delete memory by ID (permanent)
- `get_memory_history(memory_id)` - Get change history for memory
- `get_recent_memory(days?, limit?, user_id?, agent_id?)` - Get recent memories for session continuity
## Usage Examples
### Store Memory
**Auto-detect user:**
```json
{"content": "User prefers React over Vue"}
```
**With metadata:**
```json
{"content": "API endpoint changed", "metadata": {"type": "technical", "priority": "high"}}
```
**Specific user:**
```json
{"content": "Project deadline is next Friday", "user_id": "john"}
```
### Search Memories
**Basic search:**
```json
{"query": "React preferences"}
```
**With pagination:**
```json
{"query": "API endpoints", "limit": 5, "page": 2}
```
**Specific user:**
```json
{"query": "project status", "user_id": "john"}
```
### List Memories
**Auto-detect user with pagination:**
```json
{"page": 1, "page_size": 10}
```
**Specific user:**
```json
{"user_id": "john", "page": 2, "page_size": 25}
```
### Get Recent Memories
**Last week (default):**
```json
{}
```
**Last 3 days, limit 5:**
```json
{"days": 3, "limit": 5}
```
**Specific user:**
```json
{"days": 7, "user_id": "john"}
```
### Memory Management
**Get specific memory:**
```json
{"memory_id": "cafdf73c-f8c7-4729-b840-e88ce7d8a67c"}
```
**Get memory history:**
```json
{"memory_id": "cafdf73c-f8c7-4729-b840-e88ce7d8a67c"}
```
**Delete memory (permanent):**
```json
{"memory_id": "cafdf73c-f8c7-4729-b840-e88ce7d8a67c"}
```
## Architecture
### Backend Auto-Detection
1. **Mem0 Platform**: If `MEM0_API_KEY` is set
2. **OpenSearch**: If `OPENSEARCH_HOST` is set
3. **FAISS**: Default fallback (local storage in `.mem0/memory`)
### Auto User/Agent Detection
When neither `user_id` nor `agent_id` is provided, automatically detects:
- **`user_id`**: `MEM0_USER_ID` env var → system username
- **`agent_id`**: `MEM0_AGENT_ID` env var → workspace name (current directory)
This enables dual memories: user memories are personal, agent memories are workspace-specific.
### Relevance Filtering
Search results automatically filtered to return only memories with relevance score > 0.7, ensuring high-quality results.
### Error Handling
- Automatic fallback to `/tmp` if FAISS path is not writable
- Clear error messages for missing dependencies
- Graceful handling of network issues and invalid parameters
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## Citation
If you use this software in your research or project, please cite it as:
```bibtex
@software{selvam_mem0_agent_memory_2025,
author = {Selvam, Arunkumar},
title = {Mem0 Agent Memory - MCP Server},
url = {https://github.com/arunkumars-mf/mem0-agent-memory},
version = {1.0.0},
year = {2025}
}
```
## License
MIT
Raw data
{
"_id": null,
"home_page": null,
"name": "mem0-agent-memory",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "mem0, mcp, memory, ai, agent, vector-search, faiss, opensearch",
"author": null,
"author_email": "Arunkumar Selvam <aruninfy123@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/05/ed/0c07f214ca23073d51985127363e3d192061d2eab9c716562abe3724a141/mem0_agent_memory-1.0.9.tar.gz",
"platform": null,
"description": "# Mem0 Agent Memory\n\n[](https://pypi.org/project/mem0-agent-memory/)\n[](https://pepy.tech/projects/mem0-agent-memory)\n[](https://pypi.org/project/mem0-agent-memory/)\n[](https://pypi.org/project/mem0-agent-memory/)\n[](https://opensource.org/licenses/MIT)\n\nMCP server for Mem0 agent memory management with multi-backend support.\n\n## Features\n\n- **Multi-backend**: FAISS (local), OpenSearch (AWS), Mem0 Platform (cloud)\n- **AWS Bedrock integration**: Uses Amazon Titan embeddings and Claude 3.5 Haiku for processing\n- **Auto user detection**: Uses system username when no user_id provided\n- **Relevance filtering**: Returns memories with score > 0.7\n- **Complete memory operations**: store, search, list, get, delete, history\n- **Pagination support**: Handle large memory collections efficiently\n- **Recent memory tracking**: Get latest updates for session continuity\n- **Robust error handling**: Graceful fallbacks and clear error messages\n\n## Installation\n\n```bash\npip install mem0-agent-memory\n```\n\n## Quick Start\n\n```bash\n# Run directly with uvx\nuvx mem0-agent-memory\n\n# Or install and run\npip install mem0-agent-memory\npython -m mem0_agent_memory\n```\n\n## Configuration\n\n### AWS Configuration\n\nFor AWS Bedrock integration (used by default), ensure AWS credentials are configured:\n\n```bash\n# Option 1: AWS CLI configuration\naws configure\n\n# Option 2: Environment variables\nexport AWS_ACCESS_KEY_ID=\"your-access-key\"\nexport AWS_SECRET_ACCESS_KEY=\"your-secret-key\"\nexport AWS_REGION=\"us-west-2\"\n```\n\n### Environment Variables\n\n```bash\n# FAISS (default - uses .mem0/memory in current directory)\nexport FAISS_PATH=\"/path/to/memory/storage\" # Optional\n\n# OpenSearch\nexport OPENSEARCH_HOST=\"your-opensearch-endpoint\"\nexport AWS_REGION=\"us-west-2\"\n\n# Mem0 Platform\nexport MEM0_API_KEY=\"your-api-key\"\n\n# User/Agent ID (optional - auto-detects if not provided)\nexport MEM0_USER_ID=\"custom-user-id\" # Defaults to system username\nexport MEM0_AGENT_ID=\"custom-agent-id\" # Defaults to workspace name\n```\n\n### MCP Client Setup\n\n#### Amazon Q CLI\n\nCreate or edit the MCP configuration file:\n\n**Global Scope:** `~/.aws/amazonq/mcp.json`\n**Local Scope:** `.amazonq/mcp.json` (project-specific)\n\n```json\n{\n \"mcpServers\": {\n \"mem0-agent-memory\": {\n \"command\": \"uvx\",\n \"args\": [\"mem0-agent-memory\"],\n \"env\": {\n \"FAISS_PATH\": \"/Users/yourname/.mem0/agent\",\n \"MEM0_USER_ID\": \"john\",\n \"MEM0_AGENT_ID\": \"my-project\"\n }\n }\n }\n}\n```\n\n#### KIRO\n\nAdd to your KIRO MCP configuration:\n\n```json\n{\n \"mcpServers\": {\n \"mem0-agent-memory\": {\n \"command\": \"uvx\",\n \"args\": [\"mem0-agent-memory\"],\n \"env\": {\n \"FAISS_PATH\": \"/Users/yourname/.mem0/agent\",\n \"MEM0_USER_ID\": \"john\",\n \"MEM0_AGENT_ID\": \"my-project\"\n }\n }\n }\n}\n```\n\n**Agent Steering:** Use the content from [`docs/KIRO_AGENT_STEERING.md`](docs/KIRO_AGENT_STEERING.md) as your agent steering document to enable memory-first development workflows.\n\n## Tools\n\n- `store_memory(content, user_id?, agent_id?, metadata?)` - Store memory with metadata\n- `search_memories(query, user_id?, agent_id?, limit?, page?, page_size?)` - Search with relevance filtering & pagination\n- `list_memories(user_id?, agent_id?, page?, page_size?)` - List all memories with pagination\n- `get_memory(memory_id)` - Get specific memory by ID\n- `delete_memory(memory_id)` - Delete memory by ID (permanent)\n- `get_memory_history(memory_id)` - Get change history for memory\n- `get_recent_memory(days?, limit?, user_id?, agent_id?)` - Get recent memories for session continuity\n\n## Usage Examples\n\n### Store Memory\n\n**Auto-detect user:**\n```json\n{\"content\": \"User prefers React over Vue\"}\n```\n\n**With metadata:**\n```json\n{\"content\": \"API endpoint changed\", \"metadata\": {\"type\": \"technical\", \"priority\": \"high\"}}\n```\n\n**Specific user:**\n```json\n{\"content\": \"Project deadline is next Friday\", \"user_id\": \"john\"}\n```\n\n### Search Memories\n\n**Basic search:**\n```json\n{\"query\": \"React preferences\"}\n```\n\n**With pagination:**\n```json\n{\"query\": \"API endpoints\", \"limit\": 5, \"page\": 2}\n```\n\n**Specific user:**\n```json\n{\"query\": \"project status\", \"user_id\": \"john\"}\n```\n\n### List Memories\n\n**Auto-detect user with pagination:**\n```json\n{\"page\": 1, \"page_size\": 10}\n```\n\n**Specific user:**\n```json\n{\"user_id\": \"john\", \"page\": 2, \"page_size\": 25}\n```\n\n### Get Recent Memories\n\n**Last week (default):**\n```json\n{}\n```\n\n**Last 3 days, limit 5:**\n```json\n{\"days\": 3, \"limit\": 5}\n```\n\n**Specific user:**\n```json\n{\"days\": 7, \"user_id\": \"john\"}\n```\n\n### Memory Management\n\n**Get specific memory:**\n```json\n{\"memory_id\": \"cafdf73c-f8c7-4729-b840-e88ce7d8a67c\"}\n```\n\n**Get memory history:**\n```json\n{\"memory_id\": \"cafdf73c-f8c7-4729-b840-e88ce7d8a67c\"}\n```\n\n**Delete memory (permanent):**\n```json\n{\"memory_id\": \"cafdf73c-f8c7-4729-b840-e88ce7d8a67c\"}\n```\n\n## Architecture\n\n### Backend Auto-Detection\n1. **Mem0 Platform**: If `MEM0_API_KEY` is set\n2. **OpenSearch**: If `OPENSEARCH_HOST` is set\n3. **FAISS**: Default fallback (local storage in `.mem0/memory`)\n\n### Auto User/Agent Detection\nWhen neither `user_id` nor `agent_id` is provided, automatically detects:\n- **`user_id`**: `MEM0_USER_ID` env var \u2192 system username\n- **`agent_id`**: `MEM0_AGENT_ID` env var \u2192 workspace name (current directory)\n\nThis enables dual memories: user memories are personal, agent memories are workspace-specific.\n\n### Relevance Filtering\nSearch results automatically filtered to return only memories with relevance score > 0.7, ensuring high-quality results.\n\n### Error Handling\n- Automatic fallback to `/tmp` if FAISS path is not writable\n- Clear error messages for missing dependencies\n- Graceful handling of network issues and invalid parameters\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Citation\n\nIf you use this software in your research or project, please cite it as:\n\n```bibtex\n@software{selvam_mem0_agent_memory_2025,\n author = {Selvam, Arunkumar},\n title = {Mem0 Agent Memory - MCP Server},\n url = {https://github.com/arunkumars-mf/mem0-agent-memory},\n version = {1.0.0},\n year = {2025}\n}\n```\n\n## License\n\nMIT\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "MCP server for Mem0 agent memory management with multi-backend support",
"version": "1.0.9",
"project_urls": {
"Bug Reports": "https://github.com/arunkumars-mf/mem0-agent-memory/issues",
"Citation": "https://github.com/arunkumars-mf/mem0-agent-memory/blob/main/CITATION.cff",
"Homepage": "https://github.com/arunkumars-mf/mem0-agent-memory",
"Source": "https://github.com/arunkumars-mf/mem0-agent-memory"
},
"split_keywords": [
"mem0",
" mcp",
" memory",
" ai",
" agent",
" vector-search",
" faiss",
" opensearch"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "cfb912e6750de9a95d86783bfa9d40b9185325c4ebca4cc1e222a26013b86f3c",
"md5": "e7a7cdde343baaf8134cccc0074aa7eb",
"sha256": "f658d2c5b7e1d720ee4f9be97cd24cf1b1d4427ebb3328b19cb308c23636df8a"
},
"downloads": -1,
"filename": "mem0_agent_memory-1.0.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e7a7cdde343baaf8134cccc0074aa7eb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 13501,
"upload_time": "2025-09-02T18:32:12",
"upload_time_iso_8601": "2025-09-02T18:32:12.663342Z",
"url": "https://files.pythonhosted.org/packages/cf/b9/12e6750de9a95d86783bfa9d40b9185325c4ebca4cc1e222a26013b86f3c/mem0_agent_memory-1.0.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "05ed0c07f214ca23073d51985127363e3d192061d2eab9c716562abe3724a141",
"md5": "adec2f12f554dc890278de3113841ef0",
"sha256": "d056a204f56867a9ed1680fa2dace92a5c409af2372750b7144369a80b90d923"
},
"downloads": -1,
"filename": "mem0_agent_memory-1.0.9.tar.gz",
"has_sig": false,
"md5_digest": "adec2f12f554dc890278de3113841ef0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 111640,
"upload_time": "2025-09-02T18:32:13",
"upload_time_iso_8601": "2025-09-02T18:32:13.492850Z",
"url": "https://files.pythonhosted.org/packages/05/ed/0c07f214ca23073d51985127363e3d192061d2eab9c716562abe3724a141/mem0_agent_memory-1.0.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-02 18:32:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "arunkumars-mf",
"github_project": "mem0-agent-memory",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "mem0-agent-memory"
}
JSON
