MemoryHub Practical Installation and Complete Usage Guide: From Zero to Four Platform Automatic Memory Capture

Introduction

The MemoryHub installation process requires only two commands:

pip install memory-hub
memory-hub setup

However, in real deployments, you will encounter various environment differences: Docker configuration, Python versions, MCP settings, auto-start configuration, etc. This article is based on real installation experience on a Mac Studio (M3 Ultra) and documents every step from scratch to a fully running setup.

1. Environment Preparation

1.1 System Requirements

Item	Minimum Requirement	Recommended Configuration
Operating System	macOS 12+ / Linux (kernel 5.x+)	macOS 14+ / Ubuntu 22.04+
Python	3.9+	3.12
Memory	8GB	16GB+ (BGE-m3 embedding requires ~2GB)
Disk	2GB available space	10GB+ (including Qdrant data)
Docker	Docker Desktop / Docker Engine	Latest stable version

⚠️ Python Version Note: Chroma has compatibility issues on Python 3.14. If you use Python 3.14, it is recommended to choose LanceDB or use only Qdrant.

1.2 Docker Installation (Required for Qdrant)

macOS:

brew install --cask docker
# Start Docker Desktop, wait for the engine to be ready

Linux (Ubuntu):

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
# Log back in for the permissions to take effect

1.3 Verify Qdrant Container

# Start Qdrant
docker run -d -p 6333:6333 -p 6334:6334 \
  -v qdrant_storage:/qdrant/storage \
  --name mh-qdrant \
  qdrant/qdrant

# Check health status
curl http://localhost:6333/health
# Expected output: {"title":"healthz","version":"..."}

2. Install MemoryHub

2.1 One-Click Install

pip install memory-hub

If pip install memory-hub cannot be found on PyPI (new package), install directly from GitHub:
pip install git+https://github.com/Bryan-cmf/memory-hub.git

2.2 Interactive Setup Wizard

memory-hub setup

The installer guides you through six stages:

Phase 1: Environment Check
  → Check Python, pip, Docker, git
  → Detect installed AI platforms

Phase 2: Core Components (Automatic Installation)
  → Qdrant (Docker): vector search
  → SQLite: full-text index
  → MemoryHub daemon + Dashboard

Phase 3: Optional Backends (Interactive Selection)
  → [x] Qdrant (Recommended, selected)
  → [ ] Chroma (pip, no Docker)
  → [ ] LanceDB (pip, embedded)
  → [ ] SQLite-vec (lightweight vector)
  → [ ] FAISS (GPU acceleration)
  → [ ] Redis Stack (high concurrency)
  → [ ] PostgreSQL+pgvector (full-featured)
  → [ ] Elasticsearch (hybrid search)
  → [ ] MongoDB Atlas (cloud)
  → [ ] Neo4j (graph database)
  → Press Enter to skip

Phase 4: MCP Configuration
  → Automatically write MCP configuration for detected platforms

Phase 5: Verification
  → Check status of all components

Phase 6: Start daemon
  → Start the daemon now?

2.3 Manual Startup

# Start (default port 3872)
memory-hub start

# Custom port
memory-hub start --port 3880

# View status
memory-hub status

# Stop
memory-hub stop

3. MCP Configuration for Four Platforms

MCP (Model Context Protocol) is the bridge between MemoryHub and AI platforms. Once configured, the AI Agent will have memory tools.

3.1 OpenClaw

Add the following to OpenClaw's MCP configuration:

{
  "mcpServers": {
    "memory-hub": {
      "command": "python3",
      "args": ["-m", "memory_hub.server.mcp_server"],
      "env": {
        "DAEMON_HOOK_URL": "http://localhost:3872/hook",
        "QDRANT_URL": "http://localhost:6333"
      }
    }
  }
}

After restarting the AI Agent, the following tools are available: mem_save, mem_search, mem_stats, capture_send

3.2 Hermes

{
  "mcpServers": {
    "memory-hub": {
      "command": "python3",
      "args": ["-m", "memory_hub.server.mcp_server"],
      "env": {
        "DAEMON_HOOK_URL": "http://localhost:3872/hook",
        "QDRANT_URL": "http://localhost:6333"
      }
    }
  }
}

3.3 DeepSeek TUI

{
  "mcpServers": {
    "memory-hub": {
      "command": "python3",
      "args": ["-m", "memory_hub.server.mcp_server"],
      "env": {
        "DAEMON_HOOK_URL": "http://localhost:3872/hook",
        "QDRANT_URL": "http://localhost:6333"
      }
    }
  }
}

3.4 Claude Code

Claude Code's MCP configuration requires additional path settings:

{
  "mcpServers": {
    "memory-hub": {
      "command": "python3",
      "args": ["-m", "memory_hub.server.mcp_server"],
      "env": {
        "DAEMON_HOOK_URL": "http://localhost:3872/hook",
        "QDRANT_URL": "http://localhost:6333"
      }
    }
  }
}

💡 Configuration Tip: Phase 4 of the installer automatically detects the platforms you have installed and generates the corresponding MCP configuration snippet. You only need to copy and paste it into the corresponding configuration file.

4. Dashboard Usage Guide

4.1 Open the Dashboard

open http://localhost:3872

4.2 Dashboard Area Descriptions

Area	What It Displays	How to Use
Stats Bar	Today's capture count, MCP vs Scan, Qdrant points, uptime	Quick health check
Platform Cards	Captures per platform, tracked file count	Confirm whether each platform is capturing normally
24h Chart	Hourly capture trend	Understand active conversation periods
7d Chart	Daily capture trend	Understand long term usage patterns
Live Feed	Real time capture stream	Verify whether captured content is correct
Search	Full text search	Find specific conversations or memories

4.3 Understanding the Data

Today Stats:
  Captures: 247  ← Total captures today
  MCP: 12       ← Captured in real time via MCP tool
  Scan: 235     ← Captured via file scan
  Cycles: 58    ← Number of scan cycles (once every 5 minutes)
  Points: 1247  ← Total vectors in Qdrant
  Uptime: 3h    ← Daemon process runtime

A low MCP count is normal: most captures come from Mode B passive scanning
The Scan count resets to zero after a restart: the offset mechanism continues from the last position and does not count duplicates
A platform card shows 0: there may not yet be new conversations after a restart; wait a few minutes and new scans will appear

4.4 Search Tips

# Exact phrase
"customer preference"

# Filter by project (if tagged)
project:cellfie

# Filter by date
2026-05

# Combined search
2026-05 project:cellfie "due diligence"

5. Complete Command-Line Tool Reference

5.1 Core Commands

# Interactive installation
memory-hub setup

# Start daemon process
memory-hub start              # Default port 3872
memory-hub start --port 3880  # Custom port

# Status check
memory-hub status

# Stop daemon process
memory-hub stop

# Health verification
memory-hub verify
# Check items: Qdrant / Daemon / Dashboard / MCP / Files / 4 platform configs

# Backup memory
memory-hub backup --tier hourly    # Hourly backup
memory-hub backup --tier daily     # Daily snapshot
memory-hub backup --tier weekly    # Weekly archive

5.2 Common Scenarios

Scenario 1: First-Time Installation

pip install memory-hub
memory-hub setup      # Follow the wizard
memory-hub start      # Start
memory-hub verify     # Verify

Scenario 2: Daily Checks

memory-hub status     # quick check
open http://localhost:3872  # open Dashboard

Scenario 3: Troubleshooting

memory-hub stop       # Stop
memory-hub verify     # Diagnose issues
memory-hub start      # Restart

Scenario 4: Data Migration

memory-hub backup --tier weekly  # Backup data
# On a new machine
memory-hub setup
# Restore backup files to ~/.memory-hub/

6. Automatic Startup Configuration

6.1 macOS (launchd)

# Copy LaunchAgent configuration
cp ~/.memory-hub/scripts/com.memoryhub.capture-daemon.plist \
   ~/Library/LaunchAgents/

# Load and start
launchctl load ~/Library/LaunchAgents/com.memoryhub.capture-daemon.plist

# Verify
launchctl list | grep memoryhub

The daemon starts automatically at system startup and restarts automatically after a crash.

6.2 Linux (systemd)

sudo cp ~/.memory-hub/scripts/systemd/memoryhub-capture-daemon.service \
        /etc/systemd/system/
sudo systemctl enable --now memoryhub-capture-daemon

# Verification
sudo systemctl status memoryhub-capture-daemon

7. Troubleshooting Common Issues

Q1: Dashboard opens to a blank page

Cause: Possible port conflict or the daemon is not running.

# Check process
pgrep -f capture_daemon

# Check port
lsof -i :3872

# Restart
memory-hub stop && memory-hub start

Q2: Platform card keeps showing 0

Cause: Mode B scanning requires actually sending conversations before the count increases.

Solution: Send a few test messages, wait 5 minutes (the scan interval), and check the Dashboard for updates.

Q3: Qdrant connection failed

# Check Docker
docker ps | grep qdrant

# Restart Qdrant
docker restart mh-qdrant

# Check health
curl http://localhost:6333/health

Q4: MCP tools are unavailable in AI Agent

Cause: The MCP configuration has not taken effect or the path is incorrect.

Solution:

Confirm that the command path in the MCP configuration file is correct.
Restart the AI platform.
Test in an AI conversation whether mem_stats is available.

Q5: Failed to install Chroma on Python 3.14

Solution:

# Option A: Downgrade Python
# Option B: Switch to LanceDB
pip install lancedb
# In the installer, choose LanceDB instead of Chroma

Q6: Docker is not running

# macOS
open -a Docker
# Wait for Docker Desktop to fully start

# Linux
sudo systemctl start docker

8. Performance Optimization Recommendations

8.1 Embedding Model Selection

MemoryHub uses BGE-m3 by default. This is a multilingual model that performs well in Chinese scenarios. If your use case is entirely in English, consider switching to a lighter-weight model:

# Modify in ~/.memory-hub/config.json
{
  "embedding_model": "BAAI/bge-small-en-v1.5"
}

8.2 Qdrant Tuning

# Allocate more memory for Qdrant
docker run -d -p 6333:6333 \
  --memory 4g \
  -v qdrant_storage:/qdrant/storage \
  qdrant/qdrant

8.3 Scan Frequency Adjustment

# Edit in ~/.memory-hub/config.json
{
  "scan_interval_seconds": 300  # Default 5 minutes, minimum 60 seconds
}

9. Uninstall

# Stop the daemon
memory-hub stop

# Remove Qdrant
docker rm -f mh-qdrant

# Remove data (optional)
rm -rf ~/.memory-hub

# Uninstall the package
pip uninstall memory-hub -y

# Remove LaunchAgent (macOS)
launchctl unload ~/Library/LaunchAgents/com.memoryhub.capture-daemon.plist
rm ~/Library/LaunchAgents/com.memoryhub.capture-daemon.plist

Conclusion

MemoryHub's design philosophy is "two commands, running in five minutes." From pip install to seeing the first capture in the Dashboard, the whole process should not take more than ten minutes.

If you encounter any problems during installation, you can consult the official documentation:

GitHub: Bryan-cmf/memory-hub
Report issues: GitHub Issues
Full documentation: memory-hub/docs/

Make your AI Agent never forget again, starting with MemoryHub. 🧠

This article is based on actual installation experience with MemoryHub v2.0.0 (2026-05-20) in a Mac Studio M3 Ultra / macOS 15 / Python 3.12 environment.

Introduction

1. Environment Preparation

1.1 System Requirements

1.2 Docker Installation (Required for Qdrant)

1.3 Verify Qdrant Container

2. Install MemoryHub

2.1 One-Click Install

2.2 Interactive Setup Wizard

2.3 Manual Startup

3. MCP Configuration for Four Platforms

3.1 OpenClaw

3.2 Hermes

3.3 DeepSeek TUI

3.4 Claude Code

4. Dashboard Usage Guide

4.1 Open the Dashboard

4.2 Dashboard Area Descriptions

4.3 Understanding the Data

4.4 Search Tips

5. Complete Command-Line Tool Reference

5.1 Core Commands

5.2 Common Scenarios

6. Automatic Startup Configuration

6.1 macOS (launchd)

6.2 Linux (systemd)

7. Troubleshooting Common Issues

Q1: Dashboard opens to a blank page

Q2: Platform card keeps showing 0

Q3: Qdrant connection failed

Q4: MCP tools are unavailable in AI Agent

Q5: Failed to install Chroma on Python 3.14

Q6: Docker is not running

8. Performance Optimization Recommendations

8.1 Embedding Model Selection

8.2 Qdrant Tuning

8.3 Scan Frequency Adjustment

9. Uninstall

Conclusion

More in Tools