# MCP Memory System
A Model Context Protocol (MCP) server that provides enhanced file system management capabilities with agent-based workspace isolation for Large Language Models (LLMs).
## Features
- **Agent-Based Workspace Management**: Multi-agent support with isolated workspace permissions
- **File Operations**: Read, write, edit, and create files with enhanced safety checks
- **Directory Management**: Create and list directories with permission controls
- **Concurrent Safe Editing**: File locking mechanism to prevent concurrent edit conflicts
- **Media File Protection**: Prevents reading of binary files (images, videos, PDFs, etc.)
- **UTF-8 Validation**: Ensures file encoding integrity
- **Workspace Isolation**: All operations are strictly restricted to agent-specific workspace directories
- **Permission System**: Granular read/write permissions per agent with directory-level access control
## Tools Provided
### Agent Management Tools
- `register_agent`: Register an agent with automatic workspace setup (creates directory with read/write access)
- `register_agent_workspace`: Register or update an agent's workspace with custom readable and writable directory paths
- `update_agent_workspace`: Add new readable and writable directory paths to an existing agent's workspace
- `get_agent_workspace`: Get workspace configuration information for a specific agent
### File System Tools
- `write_memory_file`: Create or overwrite files with automatic directory creation (requires agent registration)
- `edit_memory_file`: Edit existing files with multiple find-and-replace operations (requires agent registration)
- `read_multiple_memory_files`: Read multiple text files at once (requires agent registration)
- `create_memory_directory`: Create directories with automatic parent creation (requires agent registration)
- `list_memory_directory`: List directory contents (requires agent registration)
- `move_memory_file`: Move or rename files (requires agent registration)
- `get_memory_files`: Get all file paths in the workspace directory with unified format output
## Usage
### 1. Agent Registration (Required)
Before performing any file operations, agents must be registered:
```python
# Simple registration - creates agent workspace directory automatically
register_agent(agent_name="my_agent", agent_workspace="my_agent")
# Or advanced registration with custom paths
register_agent_workspace(
agent_name="my_agent",
readable_paths=["shared_data", "my_agent"],
writable_paths=["my_agent", "output"]
)
```
### 2. File Operations
All file operations require the `agent_name` parameter and respect the agent's workspace permissions:
```python
# Write a file
write_memory_file(agent_name="my_agent", path="my_agent/data.txt", content="Hello World")
# Read multiple files
read_multiple_memory_files(agent_name="my_agent", paths=["my_agent/data.txt", "shared_data/config.json"])
# Edit a file
edit_memory_file(
agent_name="my_agent",
path="my_agent/data.txt",
edits=[{"oldText": "Hello", "newText": "Hi"}]
)
```
## Installation
```bash
# Install with uv
uv add mcp-memory-system
# Or install with pip
pip install mcp-memory-system
```
## Server Configuration
### Using with MCP clients
Add the following configuration to your MCP settings:
```json
{
"mcpServers": {
"memory-system": {
"command": "uv",
"args": ["--directory", "/path/to/mcp-memory-system", "run", "mcp-memory-system"],
"env": {}
}
}
}
```
### Configuration Options
- `--workspace-path`: Set the workspace directory (default: ./workspace)
## Permission System
The server implements a comprehensive permission system:
- **Agent Registration Required**: All agents must be registered before performing any memory operations
- **Directory-Level Permissions**: Permissions are granted at the directory level, not individual files
- **Read/Write Separation**: Agents can have different read and write permissions
- **Workspace Isolation**: Each agent can only access files within their permitted directories
- **Automatic Directory Creation**: Directories are created automatically when agents are registered
### Permission Examples
```python
# Agent can read from "shared" and "agent1" directories, write to "agent1" only
register_agent_workspace(
agent_name="agent1",
readable_paths=["shared", "agent1"],
writable_paths=["agent1"]
)
# Add additional permissions to existing agent
update_agent_workspace(
agent_name="agent1",
additional_readable_paths=["public_data"],
additional_writable_paths=["output"]
)
```
## Safety Features
- **Agent-Based Access Control**: Each agent can only access files within their permitted workspace directories
- **File Type Filtering**: Automatically blocks operations on binary files (images, videos, PDFs, etc.)
- **Concurrent Access Control**: File-level locking prevents data corruption during edits
- **Strict Workspace Sandboxing**: All operations are contained within the specified workspace directory
- **Path Validation**: Prevents directory traversal attacks with "../" path components
- **UTF-8 Validation**: Ensures text file integrity after operations
- **Permission Validation**: All operations validate agent permissions before execution
## Error Handling
The server provides detailed error messages for permission violations, including:
- Current agent permissions
- Specific paths that caused the error
- Suggestions for resolving permission issues
## License
MIT License - see LICENSE file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "iflow-mcp_memory-system",
"maintainer": null,
"docs_url": null,
"requires_python": "==3.12.7",
"maintainer_email": null,
"keywords": "automation, file-system, llm, mcp, memory",
"author": "Memory System Team",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/4c/df/4b1e737ca673469c06625cef29b1dbb1825ec6fc5eeca2ac6562a9367740/iflow_mcp_memory_system-0.1.2.tar.gz",
"platform": null,
"description": "# MCP Memory System\n\nA Model Context Protocol (MCP) server that provides enhanced file system management capabilities with agent-based workspace isolation for Large Language Models (LLMs).\n\n## Features\n\n- **Agent-Based Workspace Management**: Multi-agent support with isolated workspace permissions\n- **File Operations**: Read, write, edit, and create files with enhanced safety checks\n- **Directory Management**: Create and list directories with permission controls\n- **Concurrent Safe Editing**: File locking mechanism to prevent concurrent edit conflicts\n- **Media File Protection**: Prevents reading of binary files (images, videos, PDFs, etc.)\n- **UTF-8 Validation**: Ensures file encoding integrity\n- **Workspace Isolation**: All operations are strictly restricted to agent-specific workspace directories\n- **Permission System**: Granular read/write permissions per agent with directory-level access control\n\n## Tools Provided\n\n### Agent Management Tools\n- `register_agent`: Register an agent with automatic workspace setup (creates directory with read/write access)\n- `register_agent_workspace`: Register or update an agent's workspace with custom readable and writable directory paths\n- `update_agent_workspace`: Add new readable and writable directory paths to an existing agent's workspace\n- `get_agent_workspace`: Get workspace configuration information for a specific agent\n\n### File System Tools\n- `write_memory_file`: Create or overwrite files with automatic directory creation (requires agent registration)\n- `edit_memory_file`: Edit existing files with multiple find-and-replace operations (requires agent registration)\n- `read_multiple_memory_files`: Read multiple text files at once (requires agent registration)\n- `create_memory_directory`: Create directories with automatic parent creation (requires agent registration)\n- `list_memory_directory`: List directory contents (requires agent registration)\n- `move_memory_file`: Move or rename files (requires agent registration)\n- `get_memory_files`: Get all file paths in the workspace directory with unified format output\n\n## Usage\n\n### 1. Agent Registration (Required)\n\nBefore performing any file operations, agents must be registered:\n\n```python\n# Simple registration - creates agent workspace directory automatically\nregister_agent(agent_name=\"my_agent\", agent_workspace=\"my_agent\")\n\n# Or advanced registration with custom paths\nregister_agent_workspace(\n agent_name=\"my_agent\",\n readable_paths=[\"shared_data\", \"my_agent\"],\n writable_paths=[\"my_agent\", \"output\"]\n)\n```\n\n### 2. File Operations\n\nAll file operations require the `agent_name` parameter and respect the agent's workspace permissions:\n\n```python\n# Write a file\nwrite_memory_file(agent_name=\"my_agent\", path=\"my_agent/data.txt\", content=\"Hello World\")\n\n# Read multiple files\nread_multiple_memory_files(agent_name=\"my_agent\", paths=[\"my_agent/data.txt\", \"shared_data/config.json\"])\n\n# Edit a file\nedit_memory_file(\n agent_name=\"my_agent\",\n path=\"my_agent/data.txt\",\n edits=[{\"oldText\": \"Hello\", \"newText\": \"Hi\"}]\n)\n```\n\n## Installation\n\n```bash\n# Install with uv\nuv add mcp-memory-system\n\n# Or install with pip\npip install mcp-memory-system\n```\n\n## Server Configuration\n\n### Using with MCP clients\n\nAdd the following configuration to your MCP settings:\n\n```json\n{\n \"mcpServers\": {\n \"memory-system\": {\n \"command\": \"uv\",\n \"args\": [\"--directory\", \"/path/to/mcp-memory-system\", \"run\", \"mcp-memory-system\"],\n \"env\": {}\n }\n }\n}\n```\n\n### Configuration Options\n\n- `--workspace-path`: Set the workspace directory (default: ./workspace)\n\n## Permission System\n\nThe server implements a comprehensive permission system:\n\n- **Agent Registration Required**: All agents must be registered before performing any memory operations\n- **Directory-Level Permissions**: Permissions are granted at the directory level, not individual files\n- **Read/Write Separation**: Agents can have different read and write permissions\n- **Workspace Isolation**: Each agent can only access files within their permitted directories\n- **Automatic Directory Creation**: Directories are created automatically when agents are registered\n\n### Permission Examples\n\n```python\n# Agent can read from \"shared\" and \"agent1\" directories, write to \"agent1\" only\nregister_agent_workspace(\n agent_name=\"agent1\",\n readable_paths=[\"shared\", \"agent1\"],\n writable_paths=[\"agent1\"]\n)\n\n# Add additional permissions to existing agent\nupdate_agent_workspace(\n agent_name=\"agent1\",\n additional_readable_paths=[\"public_data\"],\n additional_writable_paths=[\"output\"]\n)\n```\n\n## Safety Features\n\n- **Agent-Based Access Control**: Each agent can only access files within their permitted workspace directories\n- **File Type Filtering**: Automatically blocks operations on binary files (images, videos, PDFs, etc.)\n- **Concurrent Access Control**: File-level locking prevents data corruption during edits\n- **Strict Workspace Sandboxing**: All operations are contained within the specified workspace directory\n- **Path Validation**: Prevents directory traversal attacks with \"../\" path components\n- **UTF-8 Validation**: Ensures text file integrity after operations\n- **Permission Validation**: All operations validate agent permissions before execution\n\n## Error Handling\n\nThe server provides detailed error messages for permission violations, including:\n- Current agent permissions\n- Specific paths that caused the error\n- Suggestions for resolving permission issues\n\n## License\n\nMIT License - see LICENSE file for details.",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Model Context Protocol server providing file system management tools with enhanced editing capabilities",
"version": "0.1.2",
"project_urls": null,
"split_keywords": [
"automation",
" file-system",
" llm",
" mcp",
" memory"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e6d2883dd6e3d21c5416a6374f483c17aa0012ecddd950d8daa5c17bb51e043b",
"md5": "49718d1bc690fd69a18299454d4b314f",
"sha256": "81927b5c5aa6636bb2c8a951f7eb2a02491fdd3a18c20b6f2a87dac2875cd93e"
},
"downloads": -1,
"filename": "iflow_mcp_memory_system-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "49718d1bc690fd69a18299454d4b314f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "==3.12.7",
"size": 313314,
"upload_time": "2025-09-01T09:33:59",
"upload_time_iso_8601": "2025-09-01T09:33:59.938506Z",
"url": "https://files.pythonhosted.org/packages/e6/d2/883dd6e3d21c5416a6374f483c17aa0012ecddd950d8daa5c17bb51e043b/iflow_mcp_memory_system-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4cdf4b1e737ca673469c06625cef29b1dbb1825ec6fc5eeca2ac6562a9367740",
"md5": "c53e4901a1d11e5c24427f410423e9b8",
"sha256": "57269ce9d2a103e0a9435ea5bf676ee7b793bd7a9e35600155ba799c99927e72"
},
"downloads": -1,
"filename": "iflow_mcp_memory_system-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "c53e4901a1d11e5c24427f410423e9b8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "==3.12.7",
"size": 315195,
"upload_time": "2025-09-01T09:34:01",
"upload_time_iso_8601": "2025-09-01T09:34:01.370121Z",
"url": "https://files.pythonhosted.org/packages/4c/df/4b1e737ca673469c06625cef29b1dbb1825ec6fc5eeca2ac6562a9367740/iflow_mcp_memory_system-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-01 09:34:01",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "iflow-mcp_memory-system"
}
JSON