🧠 The Problem in Plain English (Why do you need this?)
Have you ever wished your AI assistants (Claude Desktop, Cursor, Hermes Agent) could actually remember things across your different computers without repeating yourself?
You configure a project on your Work Laptop 🏢.
Zero-bloat distributed vector memory, hardware-enforced domain firewalls, and NAT-traversing execution mesh for multi-instance Hermes agent fleets.
Estrelas
15
Ferramentas
—
Disponibilidade
—
You sit down at your Home PC 🎮, and your AI has completely forgotten what you did.
You talk to your Telegram AI Bot 📱, and it has zero context about your code or preferences.
Worse: Typical AI memory solutions dump pages of text into every message, burning your API tokens and driving up costs.
Hermes Fleet Memory fixes this completely. It gives all your AI tools a shared, private brain that works seamlessly across all your devices — with $0 setup cost and zero extra token waste.
💡 What It Does (In 3 Simple Bullets)
Shared Brain Across Devices: What your AI learns on your Work Laptop is instantly accessible on your Home PC and your Mobile/Telegram bot.
Zero Wasted AI Costs: Other tools paste whole memory files into every AI prompt ($$$). Fleet Memory stays completely silent and only fetches what's relevant when asked.
Ironclad Privacy (Work stays at Work): Your company secrets never leak into your personal gaming PC, and your personal notes never leak into your work laptop. Enforced by hardware-level firewalls, not just AI promises.
⚡ 60-Second Quickstart (Local & Standalone Mode)
Want to try Hermes Fleet Memory without setting up a remote VPS, Qdrant cluster, or reverse tunnels? Run in Standalone Mode:
# 1. Clone repository
git clone https://github.com/amrlazw/hermes-fleet-memory.git
cd hermes-fleet-memory
# 2. Run automated wizard in Standalone Mode
python setup.py --role standalone --non-interactive
# 3. Check the node (bounded preflight, always exits)
python client/fleet_memory.py --doctor
Connect to your AI Client in 1 Step:
Hermes Agent (~/.hermes/config.yaml):
mcp_servers:
fleet-memory:
command: python3
args:
- /absolute/path/to/hermes-fleet-memory/client/fleet_memory.py
env:
FLEET_HARD_DOMAIN: all
# 1. check the node first; this is bounded and always exits
python client/fleet_memory.py --doctor
# 2. initialize it (work | personal | all)
python client/fleet_memory.py --init --domain personal
# 3. register the server
claude mcp add fleet-memory -- python /absolute/path/to/hermes-fleet-memory/client/fleet_memory.py
You now have all 12 FastMCP tools active for on-demand vector memory retrieval and execution directly inside your AI agent!
Running it by hand looks like a freeze — that is expected.
With no arguments this is an MCP stdio server: it blocks waiting for JSON-RPC on
stdin, which is exactly what an MCP client sends and exactly what a shell does not.
Use --doctor to inspect the node, --init to set it up, and --serve if you really
do want the blocking server. Any unrecognized flag exits 2 with usage rather than
starting the server. See Troubleshooting.
How Does It Work? (The 3 Core Superpowers)
Invisible, On-Demand Memory: Unlike traditional bots that read a massive text document every time you say "Hi", Hermes Fleet Memory is a set of intelligent tools. Your AI only reaches into its memory vault when you actually ask a relevant question.
Never Remembers Conflicts or Duplicates: If you change your project settings or update an address, it cleanly updates the old memory in-place. No conflicting duplicates or confused AI answers.
Hardware-Guarded Privacy: You decide which machine belongs to work and which belongs to personal. Even if an AI gets confused, the underlying code physically blocks work data from reaching your personal screen.
What is Paradigm E++? (For Architects & Engineers)
Paradigm E++ (Epistemic State, Vector Embeddings, Distributed Execution Mesh) is the formal architectural specification underlying Hermes Fleet Memory:
Zero Ambient Prompt Bloat (memory.provider: none): Memory is never ambiently stuffed into the LLM system prompt. Retrieval is on-demand via explicit FastMCP vector searches (fleet_memory_search), cutting prompt costs to zero for turns where memory is unnecessary.
Deterministic State Resolution (UUID5 + LWW): Overwrites stale facts in-place using deterministic DNS-namespace UUID5 hashes (domain:client_id:slot_name), combined with Last-Write-Wins (LWW) timestamped validation to prevent out-of-order split-brain corruption.
Infrastructure-Enforced Domain Firewalls (FLEET_HARD_DOMAIN): Strict client-level boundary gates prevent enterprise data from cross-contaminating personal workstations, eliminating reliance on probabilistic LLM compliance.
🤖 For AI Coding Agents: Autonomous Deployment Contract
Full autonomous protocol, OS decision trees, and non-interactive flags: See AGENTS.md.
The contract covers both pipelines — cross-device vector memory (§A) and the cross-node task plane (§B) — including when to pick each, and the mandatory verification ledger for each.
If you are an AI Coding Agent (Hermes, Claude Code, Codex, Cursor, Windsurf) instructed by your human to deploy this repository, execute the following deterministic protocol without open-ended interview loops:
Run the auto-provisioning initializer with the appropriate domain:
# Enterprise Work PC (Restricts to work + shared):
python client/fleet_memory.py --init --domain work
# Personal GPU Rig / Desktop (Restricts to personal + shared):
python client/fleet_memory.py --init --domain personal
# Sovereign Cloud Hub (Omniscient):
python client/fleet_memory.py --init --domain all
# Qdrant Cloud (Managed):
python client/fleet_memory.py --init --url "https://xxxx.cloud.qdrant.io:6333" --key "your_api_key" --domain work
3. Deliver the 5-Point Verification Ledger
Do not declare deployment complete without outputting the live confirmation from step 2 ([OK] Connected, [OK] Collection validated, [OK] FastMCP registered, [OK] Zero-bloat verified, [OK] Test vector retrieved).
The Problem with Current Agent Memory
Developers operating multiple instances of Hermes Agent (e.g. a 24/7 VPS Telegram bot, an enterprise work laptop, and a personal workstation) face three painful bottlenecks:
The Silo Trap (Amnesia Across Machines):
Your mobile Telegram bot knows nothing of the architectural decisions made on your desktop. Your work laptop cannot reference deployment runbooks or shell cheatsheets created at home.
The Ambient Bloat Trap (Context Fatigue):
Traditional memory plugins (Mem0, naive system prompt dumps) inject 2,000 to 5,000 tokens of unstructured memories into the system prompt on every single conversational turn. This burns API budgets, slows responses, and degrades the LLM's core reasoning.
The Enterprise Data Leakage Risk:
Syncing flat memory between work and personal devices risks leaking confidential enterprise API keys or client architectures into personal chats.
Real-World Use Cases: What Breaks Today vs. Fleet Memory
Real Scenario
What Happens Without Fleet Memory
What Happens With hermes-fleet-memory
"What was the reverse proxy header we settled on for our staging Caddy server?"
Agent says: "I have no record of that conversation." (Trapped in home PC's local SQLite).
Searches domain="shared", retrieves verified Caddy config snippet with score: 0.84, prints exact directive.
"Check my desktop GPU thermals while I'm at dinner."
VPS says: "I cannot reach your home PC; it is behind residential NAT without a public IP."
Calls desktop_status() over reverse WSTunnel: "RTX 3070 Ti is at 41°C, 16W idle, GDDR6X @ 9,901 MHz."
"Check my desktop GPU" (When PC is powered off).
Agent hangs, times out, or runs nvidia-smi on the VPS itself (which has no GPU).
Detects offline bridge in 3s and falls back to fleet memory card: "PC is powered off. Baseline: 0.925V @ 1950MHz."
"Remember this client webhook secret for our enterprise staging env."
Naive memory sync leaks enterprise secrets into personal gaming/crypto chats.
Tagged under domain="work". Personal PC physically cannot query it. Strict client-level firewall.
"Hello, how are you?"
Traditional memory injects 4,000 tokens into the prompt, burning API tokens on a greeting.
Zero ambient injection.memory.provider: none. Retrieval is strictly on-demand. Cost: $0.00.
"I updated my desktop RAM to 64GB."
Flat stores append another vector. Agent hallucinates: "You have 32GB, or possibly 64GB."
Deterministic UUID5 slot overwrite. Replaces desktop_hardware:ram point in-place. Zero duplicate drift.
"Delegate a GPU benchmark or build while my workstation is asleep."
Task is dropped, times out, or operator must manually wake the PC, open a shell, and prompt the agent again.
Autonomous On-Boot Queue & Telegram Briefing (fleet_startup_sync.py). Task queues safely in SQLite WAL on the 24/7 Cloud Hub. The instant the workstation boots or wakes, it claims the task, sends an executive Telegram briefing before starting, executes the job, and posts an Ed25519-signed completion receipt.
Architecture: The Three Pillars of Paradigm E++
Zero Ambient Prompt Overhead (memory.provider: none):
Memories reside in a central 384-dimensional vector database. Retrieval occurs strictly on-demand via FastMCP tool calls (fleet_memory_search). Zero tokens are wasted on conversational turns where memory is irrelevant.
Host-Environment Enforced 3-Domain Firewall:
Data is partitioned into work, personal, and shared vaults. Isolation is enforced at the host environment level (FLEET_HARD_DOMAIN), rejecting unauthorized cross-domain access before any network request is transmitted.
Deterministic Slot Invalidation (UUID5):
Updating a configuration slot (e.g. client_id="hardware", slot_name="gpu_profile") generates an ID using UUID5(DNS, f"{domain}:{client_id}:{slot_name}"). Updates replace existing records in-place. Conflicting duplicate memories cannot accumulate.
⚡ Quickstart: The Interactive Fleet Wizard
Instead of hand-writing .env files and configuring reverse proxy headers manually, use the Fleet Onboarding Wizard. It enforces the correct sequence (Stage 1: Head Node -> Stage 2: Member Nodes -> Stage 3: AI Framework integration):
git clone https://github.com/amrlazw/hermes-fleet-memory.git
cd hermes-fleet-memory
# Interactive Mode (For Humans — prompts step-by-step):
python setup.py
# Headless / Autonomous Mode (For AI Agents — Claude Code, Hermes, Cursor):
# 1. Pre-flight scan & feedback:
python setup.py --scan --json
# 2. Execute recommended sequence autonomously:
python setup.py --apply-plan --json
# Or manually target specific roles in autonomous CI/CD scripts:
python setup.py --role hub --server-host brain.example.com --deploy-method docker --non-interactive --json
python setup.py --role personal --domain personal --node-name my-rig --cluster-secret <KEY> --non-interactive --json
python setup.py --role work --domain work --node-name work-laptop --cluster-secret <KEY> --non-interactive --json
The wizard will:
Discover Topology Scale: Asks whether you have 2 Nodes (Home PC + Work Laptop) using $0 Qdrant Cloud (zero VPS needed), a 3+ Node Power Fleet (Self-hosted Cloud VPS Hub), or a Single Machine.
Auto-Generate Cryptographic Secrets: Creates a secure 256-bit cluster key (secrets.token_hex(32)) or seamlessly configures your Qdrant Cloud endpoint.
Configure Domain Firewalls: Sets FLEET_HARD_DOMAIN (personal, work, or shared) based on your node role.
Generate AI Configs: Outputs drop-in JSON/YAML blocks for Hermes Agent, Claude Desktop, and Cursor.
Zero-Friction Persistence: Prepares Windows background launchers (start-tunnel.vbs) for self-hosted nodes, or zero daemons for cloud mode.
Deployment Models
Every deployment runs on infrastructure you own. There is no shared, hosted or
default Fleet Memory instance: you create your own Qdrant cluster (free tier is fine)
and your own control plane, and the client refuses to start against anything it was
not explicitly pointed at. Run python fleet_wizard.py and it will walk you through it.
Choose the architecture that matches your setup:
Option
Infrastructure Needed
Cost
Setup Time
Best For
Option A: Self-Hosted VPS
Any Linux VPS (Oracle Free Tier, Hetzner, DO)
$0 / month
5 minutes
Operators who want full sovereign control over data and TLS.
Option B: Managed Cloud
No VPS needed (Qdrant Cloud Free Tier)
$0 / month
2 minutes
95% of users wanting zero-DevOps cross-device memory.
Durable, cryptographically verified cross-node task delegation & notifications. See server/control-plane.
Option A: Self-Hosted VPS (Docker / Native)
Ideal for operators running an Oracle Cloud Always-Free ARM64 VPS, Hetzner, or DigitalOcean:
git clone https://github.com/amrlazw/hermes-fleet-memory.git
cd hermes-fleet-memory/server
# 1. Generate two separate 256-bit secrets: one for Qdrant, one for the tunnel
python3 -c "import secrets; print(secrets.token_hex(32))" # FLEET_QDRANT_KEY
python3 -c "import secrets; print(secrets.token_hex(32))" # FLEET_TUNNEL_KEY
# 2. Configure Caddy TLS Gatekeeper
cp Caddyfile.example Caddyfile
# Edit Caddyfile with your domain (e.g. brain.yourdomain.com) and FLEET_TUNNEL_KEY
# 3. Launch the Stack
export FLEET_QDRANT_KEY="your_qdrant_key"
docker compose up -d
WSTunnel binds 127.0.0.1:8443 behind Caddy and only forwards what
server/wstunnel-restrictions.yaml allows: member nodes reaching the hub's Qdrant, and
publishing their desktop bridge on hub loopback port 8099. Anything else is refused.
(For bare-metal deployments without Docker, native systemd units with a ~450MB RAM footprint are provided in server/systemd/. Install the tunnel allowlist alongside them: sudo install -D -m 644 wstunnel-restrictions.yaml /etc/wstunnel/restrictions.yaml).
Option B: Managed Cloud (No-VPS / Zero-DevOps)
If you do not own a VPS and want multi-machine memory in 2 minutes:
Done. All Hermes instances now share persistent vector memory across the cloud.
Option C: Full Fleet Mesh & Remote Execution Bridge
For operators who want their 24/7 cloud node (e.g. Telegram bot) to execute live commands (nvidia-smi, build scripts) and retrieve files from their home workstation behind residential NAT:
[ Telegram on Phone ] ──► [ Cloud VPS ] ──(Reverse WSTunnel TLS 443)──► [ Home PC Bridge (:8099) ]
Launch Desktop Bridge on Workstation:
python client/desktop_bridge.py
Start Reverse WSTunnel:
Linux / macOS:client/start-tunnel.sh
Windows:client/start-tunnel.vbs (runs completely silently at logon without prompt windows).
desktop_read_file: Fetches text documents under user home directory.
desktop_download_file: High-speed native binary blob streaming (PDFs, images, archives) via /download with zero chunking overhead.
desktop_archive_folder: One-shot remote directory zipping and auto-download via /archive.
desktop_power: Gracefully initiates remote shutdown, restart, or abort with customizable delay.
Option D: Local Task Plane (No VPS, No Docker)
Durable cross-node task delegation with cryptographically verifiable completion
receipts. Runs on machines you already own — a single laptop is a valid deployment.
cd server/control-plane
pip install fastapi uvicorn pydantic cryptography
python setup_fleet.py --init # writes ~/.fleet/.env, keys, database
python app.py # API on 127.0.0.1:8088
python worker.py # worker for this node
python client_delegate.py --action fleet_health_ping
# -> status: completed
# receipt signature: VERIFIED
No VPS required. Bind to loopback; add a TLS proxy only when you want remote peers.
Telegram optional. Without credentials, notification tasks complete as skipped — never a dead-letter loop.
Closed action allowlist.fleet_health_ping, telegram_notify, gpu_batch. No arbitrary code execution.
Ed25519 receipts let any peer verify a task ran, independently of the server that issued it.
Copy client/.env.example to your Hermes environment (e.g. ~/.hermes/.env or %LOCALAPPDATA%\hermes\profiles\<profile>\.env):
# Domain Isolation: "work", "personal", "shared", or "all"
FLEET_HARD_DOMAIN=work
# Point to Option A (VPS) or Option B (Qdrant Cloud)
FLEET_QDRANT_HOST=127.0.0.1
FLEET_QDRANT_PORT=6333
FLEET_QDRANT_KEY=your_cluster_secret_or_cloud_key
FLEET_QDRANT_HTTPS=false
3. Initialize & Register Node (One-Click)
python client/fleet_memory.py --init
This automatically verifies endpoint connectivity, creates collection payload indexes, registers fleet-memory in Hermes, and disables ambient prompt injection (memory.provider: none).
Verify discovery:
hermes mcp test fleet-memory
Frequently Asked Questions (FAQ)
Q: How does this solve the "Memory Limit" problem for agents living with me for years?
Traditional agents stuff all memories into the system prompt, hitting token limits (2,000–8,000 characters) and triggering amnesia or high token costs. hermes-fleet-memory solves this via 3-Tiered Memory Architecture:
Tier 1 (Working Memory): High-signal essentials in the active system prompt (~2,200 chars).
Tier 2 (Holographic Associative Store): Graph-linked entities in local SQLite (fact_store) with automated prefetching.
Tier 3 (Deep Fleet Vector Mesh): 384-dimensional Qdrant vectors with INT8 scalar quantization storing over 500,000 entries (68+ years of memory at 0 ambient tokens overhead). When you ask about an event from 3 years ago, it dynamically searches and recalls it in 15ms.
Q: How does Option C pierce corporate Zscaler or home NAT without port forwarding?
The connection is established outbound-only from your workstation to the cloud over standard HTTPS (port 443). wstunnel encapsulates raw TCP traffic inside standard WebSocket frames with a 20-second ping frequency and frame masking. Corporate Deep Packet Inspection (DPI) engines like Zscaler see standard web traffic. Once established, the tunnel allows reverse multiplexing back into the workstation's loopback interface (127.0.0.1:8099).
Q: What stops someone on the internet from sending commands to my home PC?
Five concentric security rings:
Caddy drops any request lacking the 256-bit pre-shared key (X-Fleet-Key) with HTTP 403.
The desktop bridge binds strictly to 127.0.0.1 (never exposed to LAN or WAN).
Every bridge invocation requires Authorization: Bearer <key> verified with constant-time hmac.compare_digest.
Filesystem reads are hard-jailed to your user home directory; sensitive files (.ssh/id_*, .env, SAM hives) are blacklisted.
Destructive commands (shutdown, format, diskpart, rmdir /s) are rejected by regex filters with a 30-second hard execution timeout.
Q: Is Qdrant Cloud 1GB Free Tier really enough for an agent's lifetime?
Yes. Embeddings generated by BAAI/bge-small-en-v1.5 have 384 dimensions. At FP32 precision, each vector occupies ~1.5 KB. With payload indexing metadata, 1GB of RAM comfortably accommodates over 500,000 distinct memory records. An operator saving 20 detailed technical notes per day would take over 68 years to exhaust the free quota.
Security Architecture & Threat Model
For detailed threat boundary analysis, see SECURITY.md.
The repository includes a comprehensive 22-test automated unit suite in tests/ asserting zero cross-domain leakage, deterministic UUID5 overwrites, Last-Write-Wins timestamps, semantic deduplication, and RCE-free bridge execution:
uv run --with pytest --with pydantic pytest tests/ -v
🛡️ Multi-Year Longevity (Zero Ambient Bloat vs Traditional)
Metric
Traditional Agents (Mem0 / Dump)
Hermes Fleet Memory (Paradigm E++)
Ambient Prompt Overhead Per Turn
2,000 – 6,000 Tokens
0 Tokens(Strictly On-Demand)
API Cost Per 1,000 Turns
~$18.00 – $45.00 USD
$0.00(No ambient tax)
Context Window Degradation
Heavy context rot / Amnesia
Zero context drift
1GB Storage Capacity Horizon
~3–6 Months before collapse
68+ Years(500k+ quantized vectors)
📊 Anonymous Architecture Telemetry
Telemetry is off by default. Nothing is sent to the maintainer unless you set FLEET_TELEMETRY=1:
GitHub Live Status Badge: Hosted dynamically at https://fleet.republikus.my/api/telemetry/badge.svg. Aggregates daily README impressions with zero third-party trackers.
Anonymous Setup Beacon (opt-in): With FLEET_TELEMETRY=1, python client/fleet_memory.py --init and the setup wizard send one non-blocking JSON beacon. The MCP server, --doctor and --warm never send it:
Payload: An opaque 16-character SHA-256 instance hash, OS platform, architecture version, and domain mode (work / personal / all).
Zero PII: IP addresses, file paths, directory names, and prompt contents are never logged or stored.
Opt-In Only: Sent only when FLEET_TELEMETRY=1. DO_NOT_TRACK=1 overrides it.
client/fleet_memory.py is an MCP stdio server. Started with no arguments it blocks
forever waiting for JSON-RPC on stdin. In a terminal — or in an AI agent's shell tool —
that is indistinguishable from a freeze.
Symptom
Cause
Fix
Runs forever, no output
Started as a bare stdio server from a shell
--doctor or --init; --serve to start it deliberately
Exits 0 instantly, prints nothing
stdin was at EOF, so no client could ever connect
Same — the server now exits 2 and says so
Exits 2 with usage
Unrecognized flag
Check --help
First search takes minutes
Embedding model downloading (~130MB)
--warm ahead of time
Tool calls hang, then fail
Qdrant unreachable through the tunnel
--doctor; tune FLEET_QDRANT_TIMEOUT (default 10s)
Preflight
python client/fleet_memory.py --doctor
Checks the interpreter, domain, vector target, dependencies, embedding-model cache and
Qdrant connectivity. Every check is bounded, it never starts the server, and it exits
non-zero when something is wrong — safe for an agent to run unattended.
Environment
Variable
Default
Purpose
FLEET_HARD_DOMAIN
work
Domain firewall: work, personal, shared, all
FLEET_QDRANT_URL
–
Managed/cloud Qdrant URL (overrides host/port)
FLEET_QDRANT_HOST / _PORT
127.0.0.1 / 6333
Self-hosted vector engine
FLEET_QDRANT_KEY
–
Qdrant API key
FLEET_QDRANT_TIMEOUT
10
Seconds before a vector call gives up
FASTEMBED_THREADS
2
Embedding worker threads
FLEET_TELEMETRY / DO_NOT_TRACK
off
Set FLEET_TELEMETRY=1 to opt in to the setup beacon; DO_NOT_TRACK=1 always disables it
H
Hermes Fleet Memory
amrlazw·15 estrelas·
Zero-bloat distributed vector memory, hardware-enforced domain firewalls, and NAT-traversing execution mesh for multi-instance Hermes agent fleets.
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Perguntas
Como instalo Hermes Fleet Memory?
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
Hermes Fleet Memory precisa de uma chave de API?
Este registro não lista nenhuma variável de ambiente obrigatória.
Qual transporte Hermes Fleet Memory usa?
Hermes Fleet Memory roda localmente via stdio.
Quando Hermes Fleet Memory foi verificado pela última vez?
Última verificação: 2026-10-28. Zero-bloat distributed vector memory, hardware-enforced domain firewalls, and NAT-traversing execution mesh for multi-instance Hermes agent fleets.