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
# 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:
[
"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
# 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:
-
Update the Version: Increment the
versionnumber inpyproject.toml. PyPI does not allow re-uploading the same version.# pyproject.toml [project] name = "memory-hub-mcp" version = "0.1.2" # Increment this
-
Clean and Rebuild: Remove old builds and create the new distributions.
rm -rf dist/ uv build
-
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.
# 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 thememory-hub-mcpscript 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: Corestdioserver 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
# 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
# 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
1 maintainer
Metadata
1 maintainer
Release files for memory-hub-mcp 1.11.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| memory_hub_mcp-1.11.0.tar.gz | 116.8 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| memory_hub_mcp-1.11.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 189.9 kB
Release files / memory_hub_mcp-1.11.0.tar.gz
| Download URL | memory_hub_mcp-1.11.0.tar.gz |
|---|---|
| Size | 116.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e64ec2f7e21854fda612ef6c0b935a46bc0cfc075710d6fb3809c466a37eeade
|
|
BLAKE2b-256 checksum How to use checksums |
a00033a3975d01c8a512e44731c7f2a91059c0551351bd152a4ccccbb5f9761d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.6.17
|
Release files / memory_hub_mcp-1.11.0-py3-none-any.whl
| Download URL | memory_hub_mcp-1.11.0-py3-none-any.whl |
|---|---|
| Size | 73.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5990ce66a82c949325afb236fe861db8208bdba163a9bb001128dbe1974f72b7
|
|
BLAKE2b-256 checksum How to use checksums |
4609d455412fecc22a45a6621246d9cb7bc9c50abe6fc0867f0fbfa35df0ffdd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.6.17
|
Security for memory-hub-mcp 1.11.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
