| Name | memory-hub-mcp JSON |
| Version |
0.2.1
JSON |
| download |
| home_page | None |
| Summary | Local Memory Hub MCP Server with stdio transport for ZenCoder and MCP clients |
| upload_time | 2025-07-15 18:50:56 |
| maintainer | None |
| docs_url | None |
| author | Matt |
| requires_python | >=3.11 |
| license | MIT |
| keywords |
ai
mcp
memory
stdio
vector-search
zencoder
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Memory Hub MCP Server (UV/UVX)
A local memory hub for AI agents with MCP integration, designed for ZenCoder and other MCP clients using stdio transport.
## Quick Start with UVX
### Installation & Usage
```bash
# Install and run directly with uvx
uvx memory-hub-mcp
# Or install locally first
uv pip install memory-hub-mcp
memory-hub-mcp
```
### For ZenCoder Integration
In ZenCoder's custom MCP server configuration, you must now provide the URLs for the dependent services (Qdrant and LM Studio).
**Command:** `uvx`
**Arguments:**
```json
[
"memory-hub-mcp",
"--qdrant-url",
"http://<ip_address_of_qdrant>:6333",
"--lm-studio-url",
"http://<ip_address_of_lm_studio>:1234/v1"
]
```
> **Note:** Replace `<ip_address_...>` with the actual IP addresses where your services are running. If they are on the same machine, the IP will be the same for both.
## Development Setup
```bash
# Clone and setup
git clone <your-repo>
cd memory-hub
uv venv
source .venv/bin/activate
uv pip install -e .
# Run in development
memory-hub-mcp --log-level DEBUG --qdrant-url http://localhost:6333 --lm-studio-url http://localhost:1234/v1
```
## Publishing to PyPI
To publish a new version of the package to PyPI:
1. **Update the Version**: Increment the `version` number in `pyproject.toml`. PyPI does not allow re-uploading the same version.
```toml
# pyproject.toml
[project]
name = "memory-hub-mcp"
version = "0.1.2" # Increment this
```
2. **Clean and Rebuild**: Remove old builds and create the new distributions.
```bash
rm -rf dist/
uv build
```
3. **Publish with an API Token**:
The recommended way to publish is to use a PyPI API token. You can provide it directly to the command via an environment variable for security.
```bash
# Replace <your_pypi_token> with your actual token
UV_PUBLISH_TOKEN=<your_pypi_token> uv publish dist/*
```
## Available Tools
- **add_memory**: Store content with hierarchical metadata (app_id, project_id, ticket_id)
- **search_memories**: Semantic search with keyword enhancement and LLM synthesis
- **get_project_memories**: Retrieve ALL memories for a specific app_id/project_id without search queries
- **update_memory**: Update existing memories with automatic version incrementing
- **get_recent_memories**: Retrieve memories from the last N hours (perfect for resuming work)
- **list_app_ids**: List all application IDs
- **list_project_ids**: List all project IDs
- **list_ticket_ids**: List all ticket IDs
- **list_memory_types**: List memory types currently in use (with counts and metadata)
- **get_memory_type_guide**: Get the recommended memory type conventions
- **health_check**: Server health status
## Configuration
The server expects:
- **Qdrant**: Vector database running (see docker-compose.yml)
- **LM Studio**: For embeddings and chat completions
- **Environment**: Standard .env configuration
## Key File & Directory Locations
- **`pyproject.toml`**: Defines project metadata, dependencies, and the `memory-hub-mcp` script entry point.
- **`src/memory_hub/`**: The main Python package source code.
- **`src/memory_hub/cli.py`**: The command-line interface logic that launches the server.
- **`src/memory_hub/mcp_server.py`**: Core `stdio` server implementation and tool registration.
- **`src/memory_hub/core/handlers/`**: Contains the implementation for each MCP tool (e.g., `add_memory`, `search_memories`).
- **`src/memory_hub/core/services.py`**: Handles communication with external services like Qdrant and LM Studio.
- **`src/memory_hub/core/models.py`**: Pydantic models defining the data structures used throughout the application.
- **`docker-compose.yml`**: Defines the Qdrant service dependency.
## Architecture
- **stdio transport**: Direct MCP protocol communication
- **No HTTP dependencies**: Lightweight, focused on MCP clients
- **Hierarchical memory**: Flexible app/project/ticket organization
- **Hybrid search**: Vector similarity + keyword matching + LLM synthesis
- **Version management**: Automatic versioning for memory updates
- **Time-based retrieval**: Query recent memories by hours
## Agent Usage Guide
### Saving Agent Progress
```python
# Save initial work
add_memory(
content="Implemented user authentication with JWT tokens...",
metadata={
"app_id": "eatzos",
"project_id": "next",
"type": "feature_implementation"
}
)
# Update existing memory
update_memory(
app_id="eatzos",
project_id="next",
memory_type="feature_implementation",
new_content="Completed authentication with JWT tokens and added refresh token logic..."
)
```
### Resuming Agent Work
```python
# Get ALL context for a project (no search guessing!)
get_project_memories(
app_id="eatzos",
project_id="next",
limit=50
)
# See what changed recently
get_recent_memories(
app_id="eatzos",
hours=24,
include_summary=True
)
```
## Differences from HTTP Version
This UV/UVX version:
- ✅ Uses stdio transport (ZenCoder compatible)
- ✅ No FastAPI dependencies
- ✅ Lightweight packaging
- ✅ Direct MCP protocol
- ❌ No web interface
- ❌ No HTTP endpoints
Raw data
{
"_id": null,
"home_page": null,
"name": "memory-hub-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "ai, mcp, memory, stdio, vector-search, zencoder",
"author": "Matt",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/0d/5c/8ee49b154412168eab32001f28dc5d19f8b0ea42f0094910ac6d4c9128f4/memory_hub_mcp-0.2.1.tar.gz",
"platform": null,
"description": "# Memory Hub MCP Server (UV/UVX)\n\nA local memory hub for AI agents with MCP integration, designed for ZenCoder and other MCP clients using stdio transport.\n\n## Quick Start with UVX\n\n### Installation & Usage\n\n```bash\n# Install and run directly with uvx\nuvx memory-hub-mcp\n\n# Or install locally first\nuv pip install memory-hub-mcp\nmemory-hub-mcp\n```\n\n### For ZenCoder Integration\n\nIn ZenCoder's custom MCP server configuration, you must now provide the URLs for the dependent services (Qdrant and LM Studio).\n\n**Command:** `uvx`\n\n**Arguments:** \n```json\n[\n \"memory-hub-mcp\",\n \"--qdrant-url\",\n \"http://<ip_address_of_qdrant>:6333\",\n \"--lm-studio-url\",\n \"http://<ip_address_of_lm_studio>:1234/v1\"\n]\n```\n> **Note:** Replace `<ip_address_...>` with the actual IP addresses where your services are running. If they are on the same machine, the IP will be the same for both.\n\n## Development Setup\n\n```bash\n# Clone and setup\ngit clone <your-repo>\ncd memory-hub\nuv venv\nsource .venv/bin/activate\nuv pip install -e .\n\n# Run in development\nmemory-hub-mcp --log-level DEBUG --qdrant-url http://localhost:6333 --lm-studio-url http://localhost:1234/v1\n```\n\n## Publishing to PyPI\n\nTo publish a new version of the package to PyPI:\n\n1. **Update the Version**: Increment the `version` number in `pyproject.toml`. PyPI does not allow re-uploading the same version.\n \n ```toml\n # pyproject.toml\n [project]\n name = \"memory-hub-mcp\"\n version = \"0.1.2\" # Increment this\n ```\n\n2. **Clean and Rebuild**: Remove old builds and create the new distributions.\n \n ```bash\n rm -rf dist/\n uv build\n ```\n\n3. **Publish with an API Token**:\n \n The recommended way to publish is to use a PyPI API token. You can provide it directly to the command via an environment variable for security.\n \n ```bash\n # Replace <your_pypi_token> with your actual token\n UV_PUBLISH_TOKEN=<your_pypi_token> uv publish dist/*\n ```\n\n## Available Tools\n\n- **add_memory**: Store content with hierarchical metadata (app_id, project_id, ticket_id)\n- **search_memories**: Semantic search with keyword enhancement and LLM synthesis\n- **get_project_memories**: Retrieve ALL memories for a specific app_id/project_id without search queries\n- **update_memory**: Update existing memories with automatic version incrementing\n- **get_recent_memories**: Retrieve memories from the last N hours (perfect for resuming work)\n- **list_app_ids**: List all application IDs\n- **list_project_ids**: List all project IDs \n- **list_ticket_ids**: List all ticket IDs\n- **list_memory_types**: List memory types currently in use (with counts and metadata)\n- **get_memory_type_guide**: Get the recommended memory type conventions\n- **health_check**: Server health status\n\n## Configuration\n\nThe server expects:\n- **Qdrant**: Vector database running (see docker-compose.yml)\n- **LM Studio**: For embeddings and chat completions\n- **Environment**: Standard .env configuration\n\n## Key File & Directory Locations\n\n- **`pyproject.toml`**: Defines project metadata, dependencies, and the `memory-hub-mcp` script entry point.\n- **`src/memory_hub/`**: The main Python package source code.\n- **`src/memory_hub/cli.py`**: The command-line interface logic that launches the server.\n- **`src/memory_hub/mcp_server.py`**: Core `stdio` server implementation and tool registration.\n- **`src/memory_hub/core/handlers/`**: Contains the implementation for each MCP tool (e.g., `add_memory`, `search_memories`).\n- **`src/memory_hub/core/services.py`**: Handles communication with external services like Qdrant and LM Studio.\n- **`src/memory_hub/core/models.py`**: Pydantic models defining the data structures used throughout the application.\n- **`docker-compose.yml`**: Defines the Qdrant service dependency.\n\n## Architecture\n\n- **stdio transport**: Direct MCP protocol communication\n- **No HTTP dependencies**: Lightweight, focused on MCP clients\n- **Hierarchical memory**: Flexible app/project/ticket organization\n- **Hybrid search**: Vector similarity + keyword matching + LLM synthesis\n- **Version management**: Automatic versioning for memory updates\n- **Time-based retrieval**: Query recent memories by hours\n\n## Agent Usage Guide\n\n### Saving Agent Progress\n```python\n# Save initial work\nadd_memory(\n content=\"Implemented user authentication with JWT tokens...\",\n metadata={\n \"app_id\": \"eatzos\",\n \"project_id\": \"next\",\n \"type\": \"feature_implementation\"\n }\n)\n\n# Update existing memory\nupdate_memory(\n app_id=\"eatzos\",\n project_id=\"next\", \n memory_type=\"feature_implementation\",\n new_content=\"Completed authentication with JWT tokens and added refresh token logic...\"\n)\n```\n\n### Resuming Agent Work\n```python\n# Get ALL context for a project (no search guessing!)\nget_project_memories(\n app_id=\"eatzos\",\n project_id=\"next\",\n limit=50\n)\n\n# See what changed recently\nget_recent_memories(\n app_id=\"eatzos\",\n hours=24,\n include_summary=True\n)\n```\n\n## Differences from HTTP Version\n\nThis UV/UVX version:\n- \u2705 Uses stdio transport (ZenCoder compatible)\n- \u2705 No FastAPI dependencies\n- \u2705 Lightweight packaging\n- \u2705 Direct MCP protocol\n- \u274c No web interface\n- \u274c No HTTP endpoints ",
"bugtrack_url": null,
"license": "MIT",
"summary": "Local Memory Hub MCP Server with stdio transport for ZenCoder and MCP clients",
"version": "0.2.1",
"project_urls": null,
"split_keywords": [
"ai",
" mcp",
" memory",
" stdio",
" vector-search",
" zencoder"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e84962ee0d8608db29845abff2a3b1cf01acaef901e977ac5fb2b24007541baf",
"md5": "61c4c3cdd4ffb0707379e021766cb40c",
"sha256": "4884540a26533e2bf97ab9b1d8d2643c01df2168f5fd49a02fce229a2ec55c22"
},
"downloads": -1,
"filename": "memory_hub_mcp-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "61c4c3cdd4ffb0707379e021766cb40c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 32010,
"upload_time": "2025-07-15T18:50:54",
"upload_time_iso_8601": "2025-07-15T18:50:54.031609Z",
"url": "https://files.pythonhosted.org/packages/e8/49/62ee0d8608db29845abff2a3b1cf01acaef901e977ac5fb2b24007541baf/memory_hub_mcp-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0d5c8ee49b154412168eab32001f28dc5d19f8b0ea42f0094910ac6d4c9128f4",
"md5": "78c8357c2fe67f06bd6fd71618d26215",
"sha256": "5d80439041b334604a577d42ab39c4d0b02daf9fab144c720c1d92da812c8975"
},
"downloads": -1,
"filename": "memory_hub_mcp-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "78c8357c2fe67f06bd6fd71618d26215",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 3463834,
"upload_time": "2025-07-15T18:50:56",
"upload_time_iso_8601": "2025-07-15T18:50:56.366028Z",
"url": "https://files.pythonhosted.org/packages/0d/5c/8ee49b154412168eab32001f28dc5d19f8b0ea42f0094910ac6d4c9128f4/memory_hub_mcp-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-15 18:50:56",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "memory-hub-mcp"
}
