hermes-fleet-memory

<div align="center"> <a href="https://github.com/amrlazw/hermes-fleet-memory"> <img src="assets/banner.svg" alt="Hermes Fleet Memory" width="100%"> </a> <p align="center"> <a href="https://fleet.republikus.my/api/telemetry/badge.svg"><img src="https://fleet.republikus.my/api/telemetry/badge.svg" alt="Fleet Memory Badge"></a> <a href="https://m8ven.ai/mcp/amrlazw-hermes-fleet-memory-nnsvq2"><img src="https://m8ven.ai/badge/mcp/amrlazw-hermes-fleet-memory-nnsvq2" alt="M8ven Trust Score"></a> <a href="https://github.com/amrlazw/hermes-fleet-memory/actions"><img src="https://img.shields.io/badge/CI_BUILD-PASSING-059669?style=flat-square&logo=githubactions&logoColor=white&labelColor=111827" alt="CI"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/LICENSE-MIT-3b82f6?style=flat-square&logo=opensourceinitiative&logoColor=white&labelColor=111827" alt="License"></a> <a href="PRIVACY.md"><img src="https://img.shields.io/badge/PRIVACY-POLICY-10b981?style=flat-square&logo=shield&logoColor=white&labelColor=111827" alt="Privacy Policy"></a> <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/FASTMCP-2.X_READY-10b981?style=flat-square&logo=anthropic&logoColor=white&labelColor=111827" alt="FastMCP"></a> <a href="https://qdrant.tech/"><img src="https://img.shields.io/badge/VECTOR_DB-QDRANT_INT8-ef4444?style=flat-square&logo=qdrant&logoColor=white&labelColor=111827" alt="Qdrant"></a> <a href="#"><img src="https://img.shields.io/badge/PROMPT_OVERHEAD-0_TOKENS-06b6d4?style=flat-square&logo=speedtest&logoColor=white&labelColor=111827" alt="Zero Overhead"></a> <a href="#"><img src="https://img.shields.io/badge/ARCHITECTURE-PARADIGM_E%2B%2B-8b5cf6?style=flat-square&logo=hyper&logoColor=white&labelColor=111827" alt="Paradigm E++"></a> <a href="#"><img src="https://img.shields.io/badge/PYTHON-3.10%2B-f59e0b?style=flat-square&logo=python&logoColor=white&labelColor=111827" alt="Python 3.10+"></a> </p> </div> --- ### 🧠 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** 🏢. * 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) 1. **Shared Brain Across Devices:** What your AI learns on your Work Laptop is instantly accessible on your Home PC and your Mobile/Telegram bot. 2. **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. 3. **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**: ```bash # 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`):** ```yaml mcp_servers: fleet-memory: command: python3 args: - /absolute/path/to/hermes-fleet-memory/client/fleet_memory.py env: FLEET_HARD_DOMAIN: all ``` **Claude Desktop (`claude_desktop_config.json`):** ```json { "mcpServers": { "fleet-memory": { "command": "python3", "args": ["/absolute/path/to/hermes-fleet-memory/client/fleet_memory.py"], "env": { "FLEET_HARD_DOMAIN": "all" } } } } ``` **Claude Code (CLI) — one command:** ```bash # 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](#troubleshooting). --- ### How Does It Work? (The 3 Core Superpowers) 1. **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. 2. **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. 3. **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: 1. **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. 2. **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. 3. **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. --- ``` ┌────────────────────────────────────────────────────────┐ │ HERMES FLEET MESH │ └────────────────────────────────────────────────────────┘ │ ┌────────────────────────────────────────┼────────────────────────────────────────┐ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ NODE 1 │ │ NODE 2 │ │ NODE 3 │ │ Central Hub │ │ Work PC │ │ Home Rig │ │ (Cloud VPS) │ │ (Corporate) │ │ (Workstation)│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ │ │ │ Telegram Gateway (@Bot) │ Corporate Zscaler / MDM │ Local GPU Inference │ FLEET_HARD_DOMAIN=all │ FLEET_HARD_DOMAIN=work │ FLEET_HARD_DOMAIN=personal │ FastMCP stdio client │ FastMCP stdio client │ FastMCP stdio client │ │ │ └───────────────────┬────────────────────┴───────────────────┬────────────────────┘ │ │ ▼ ▼ ┌──────────────────────────┐ ┌──────────────────────────┐ │ Qdrant Vector DB │ │ Desktop Bridge (:8099) │ │ (VPS Native or Managed) │ │ (Live Exec & File Read) │ └──────────────────────────┘ └──────────────────────────┘ ``` --- <!-- ============================================================================== --> <!-- AGENT RUNBOOK CONTRACT: READ THIS FIRST --> <!-- ============================================================================== --> ## 🤖 For AI Coding Agents: Autonomous Deployment Contract > **Full autonomous protocol, OS decision trees, and non-interactive flags:** See [AGENTS.md](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: ### 1. Install Dependencies Install in the active Python environment: ```bash pip install "mcp[cli]" qdrant-client fastembed python-dotenv ``` ### 2. Autonomous Initialization (One Command) Run the auto-provisioning initializer with the appropriate domain: ```bash # 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`). <!-- ============================================================================== --> <!-- END AGENT RUNBOOK CONTRACT --> <!-- ============================================================================== --> --- ## The Problem with Current Agent Memory Developers operating multiple instances of [Hermes Agent](https://github.com/NousResearch/hermes-agent) (e.g. a 24/7 VPS Telegram bot, an enterprise work laptop, and a personal workstation) face three painful bottlenecks: 1. **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. 2. **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. 3. **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++ 1. **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. 2. **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. 3. **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**): ```bash 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: 1. **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**. 2. **Auto-Generate Cryptographic Secrets:** Creates a secure 256-bit cluster key (`secrets.token_hex(32)`) or seamlessly configures your Qdrant Cloud endpoint. 3. **Configure Domain Firewalls:** Sets `FLEET_HARD_DOMAIN` (`personal`, `work`, or `shared`) based on your node role. 4. **Generate AI Configs:** Outputs drop-in JSON/YAML blocks for **Hermes Agent**, **Claude Desktop**, and **Cursor**. 5. **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. | | **Option C: Full Fleet Mesh** | Home PC + Relay VPS | $0 / month | 10 minutes | Remote shell command execution & file retrieval behind NAT. | | **Option D: Local Task Plane** | **None** (runs on machines you already have) | **$0 / month** | **2 minutes** | Durable, cryptographically verified cross-node task delegation & notifications. See [`server/control-plane`](server/control-plane/README.md). | --- ### Option A: Self-Hosted VPS (Docker / Native) Ideal for operators running an Oracle Cloud Always-Free ARM64 VPS, Hetzner, or DigitalOcean: ```bash 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: 1. Create a free account at [Qdrant Cloud](https://cloud.qdrant.io/). 2. Launch a **1GB Free Tier Cluster** ($0 permanent free tier, holding 500,000+ memory vectors). 3. Copy your **Cluster URL** (`https://xxxx.cloud.qdrant.io:6333`) and **API Key**. 4. Configure each client machine's `.env`: ```ini FLEET_QDRANT_URL=https://xxxx.cloud.qdrant.io:6333 FLEET_QDRANT_KEY=your_qdrant_cloud_api_key FLEET_QDRANT_HTTPS=true ``` *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) ] ``` 1. **Launch Desktop Bridge on Workstation:** ```bash python client/desktop_bridge.py ``` 2. **Start Reverse WSTunnel:** - **Linux / macOS:** `client/start-tunnel.sh` - **Windows:** `client/start-tunnel.vbs` (runs completely silently at logon without prompt windows). 3. **Unlocked Capabilities (Bridge v2 & Knowledge Graph):** - `fleet_graph_search`: Traverses multi-hop Knowledge Graph relationships across entities (`[[Entity]]`) without dedicated graph database overhead. - `desktop_status`: Returns live GPU temperature, VRAM usage, and workstation heartbeat. - `desktop_exec`: Executes safe, sandboxed commands remotely. - `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. ```bash 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. Full operations guide: [`server/control-plane/RUNBOOK.md`](server/control-plane/RUNBOOK.md) --- ## Client Setup (Every Machine) ### 1. Install Dependencies ```bash pip install "mcp[cli]" qdrant-client fastembed python-dotenv ``` ### 2. Configure Environment Copy `client/.env.example` to your Hermes environment (e.g. `~/.hermes/.env` or `%LOCALAPPDATA%\hermes\profiles\<profile>\.env`): ```ini # 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) ```bash 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: ```bash 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**: 1. **Tier 1 (Working Memory):** High-signal essentials in the active system prompt (~2,200 chars). 2. **Tier 2 (Holographic Associative Store):** Graph-linked entities in local SQLite (`fact_store`) with automated prefetching. 3. **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:** 1. Caddy drops any request lacking the 256-bit pre-shared key (`X-Fleet-Key`) with HTTP 403. 2. The desktop bridge binds strictly to `127.0.0.1` (never exposed to LAN or WAN). 3. Every bridge invocation requires `Authorization: Bearer <key>` verified with constant-time `hmac.compare_digest`. 4. Filesystem reads are hard-jailed to your user home directory; sensitive files (`.ssh/id_*`, `.env`, SAM hives) are blacklisted. 5. 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](SECURITY.md). ``` [ Ingress TLS / Port 443 ] ──► [ Caddy Token Gate ] ──► [ Loopback Jail :8099 ] ──► [ Constant-Time HMAC ] ──► [ Sandboxed Shell ] ``` ### Automated Negative Security, Deduplication & Concurrency Tests 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: ```bash uv run --with pytest --with pydantic pytest tests/ -v ``` ```text tests/test_bridge_security.py::test_constant_time_hmac_auth PASSED tests/test_bridge_security.py::test_command_allowlist_rejects_unauthorized_binaries PASSED tests/test_bridge_security.py::test_command_allowlist_accepts_authorized_binaries PASSED tests/test_bridge_security.py::test_command_allowlist_rejects_dangerous_arguments PASSED tests/test_bridge_security.py::test_predeclared_actions PASSED tests/test_bridge_security.py::test_path_jail_blocks_traversal PASSED tests/test_bridge_security.py::test_blocked_file_substrings PASSED tests/test_cleaner.py::test_archive_points PASSED tests/test_cleaner.py::test_clean_expired_memories_performs_hard_deletion PASSED tests/test_dedup.py::test_provenance_attribution PASSED tests/test_dedup.py::test_semantic_dedup_updates_existing_point PASSED tests/test_domain_isolation.py::test_personal_node_allowed_domains PASSED tests/test_domain_isolation.py::test_personal_node_denied_work_query PASSED tests/test_domain_isolation.py::test_personal_node_denied_all_query PASSED tests/test_domain_isolation.py::test_work_node_allowed_domains PASSED tests/test_domain_isolation.py::test_work_node_denied_personal_query PASSED tests/test_domain_isolation.py::test_work_node_denied_personal_store PASSED tests/test_domain_isolation.py::test_personal_node_denied_work_store PASSED tests/test_domain_isolation.py::test_cloud_sentinel_all_access PASSED tests/test_lww_concurrency.py::test_uuid5_deterministic_slot_generation PASSED tests/test_lww_concurrency.py::test_lww_monotonic_revision_increment PASSED tests/test_lww_concurrency.py::test_lww_rejects_stale_concurrent_write PASSED ============================= 22 passed in 0.10s ============================== ``` --- ## Native Terminal Telemetry CLI (`fleet`) To monitor live fleet vitals from any terminal without opening a browser: ```bash # High-density ASCII bento layout fleet # Raw JSON output for script pipelines fleet raw ``` ```text ┌────┬────────────┬─────────────────────────────┬──────────────┬───────────────────────────┐ │ ID │ NODE │ ROLE │ DOMAIN LOCK │ STATUS / VITALS │ ├────┼────────────┼─────────────────────────────┼──────────────┼───────────────────────────┤ │ node1 │ Chester │ 24/7 Cloud Sentinel & Teleg │ all │ ONLINE Idle < 2% (Hub) │ │ node2 │ Wolf │ Enterprise Presales AI Solu │ work │ ONLINE Zscaler (~18ms) │ │ node3 │ Winston │ Personal Butler & GPU Works │ personal │ ONLINE RTX 3070 Ti (:8099)│ └────┴────────────┴─────────────────────────────┴──────────────┴───────────────────────────┘ FastMCP Stdio: Synchronized │ LWW Concurrency: Active │ INT8 Quant: Enabled ``` --- ## Benchmarks & Performance Evidence Rigorous cross-hardware benchmarking measured between **Node 1** (Oracle Cloud ARM64 A1.Flex / 4 OCPU / 24GB RAM) and **Node 3** (Windows 11 / AMD Ryzen / NVIDIA RTX 3070 Ti 8GB): ### ⚡ Latency & Vector Operations | Metric / Operation | Oracle ARM64 (NEON) | Windows 11 (AVX2) | Delta / Target | | :--- | :--- | :--- | :--- | | **Embedding Generation (`bge-small-en-v1.5`)** | ~14.2 ms / chunk | ~8.6 ms / chunk | Sub-15ms local ONNX runtime | | **Vector Search Execution (Qdrant INT8)** | 8.4 ms (indexed) | 11.2 ms (remote TLS) | Sub-15ms query response | | **Cross-Architecture Cosine Parity** | `0.8389` | `0.8390` | **99.98% deterministic parity** | | **Tunnel Round-Trip Overhead (`wstunnel`)** | <3.8 ms | <4.1 ms | Indistinguishable from raw TCP | --- ### 🚀 Desktop Bridge v2 Throughput & Memory Efficiency | Bridge v2 Benchmark | Previous (Bridge v1) | Current (Bridge v2) | Improvement | | :--- | :--- | :--- | :--- | | **Binary Retrieval (`/download` 1MB Payslip/PDF)** | 14.8s *(Chunked Base64)* | **0.18s** *(Direct Stream)* | **82x Faster** | | **Directory Archiving (`/archive` on-the-fly)** | N/A *(Manual script)* | **0.42s** *(Zstandard/Zip)* | Instant directory sync | | **HMAC Auth Verification Latency** | ~2.1 ms | **0.08 ms** | Constant-time hardening | | **Console Window Allocation during Exec** | 1 ms flash *(cmd.exe)* | **0.00 ms** *(pythonw.exe)* | **100% Zero-Window Silent** | | **RAM Footprint (Standby)** | ~85 MB | **~24 MB** *(Pure stdlib)* | **71% RAM Reduction** | --- ### 🛡️ 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`: 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. 2. **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. --- ## License MIT © 2026 Mohamad Amirul Azwan --- ## Troubleshooting ### The command hangs / nothing is printed `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 ```bash 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 |