hexus 0.9.0__tar.gz

hexus-0.9.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Andrea Borghi
+Copyright (c) 2026, Hexus Contributors
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

hexus-0.9.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: hexus
+Version: 0.9.0
+Summary: Hexus: Postgres + hexus memory provider plugin for hermes-agent AND a standalone MCP server. Local BERT (MiniLM-L6-v2) embeddings replace the upstream HTTP embedder; multi-agent storage with per-minion themes, async writer, no LLM in the memory hot path.
+Author: Andrea Borghi
+Author-email: Toby <codenamekt@gmail.com>
+License: BSD-3-Clause
+Project-URL: Homepage, https://github.com/codenamekt/hexus
+Project-URL: Source, https://github.com/codenamekt/hexus
+Project-URL: Upstream, https://github.com/andreab67/hermes-hexus
+Project-URL: Issues, https://github.com/codenamekt/hexus/issues
+Project-URL: Roadmap, https://github.com/codenamekt/hexus/blob/main/PLAN.md
+Keywords: hermes-agent,memory-provider,hexus,postgres,multi-agent,llm-memory,semantic-search,bert,sentence-transformers,local-embeddings,mcp,model-context-protocol,hexus
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: psycopg[binary]<4,>=3.3.4
+Requires-Dist: psycopg-pool<4,>=3.3.1
+Requires-Dist: PyYAML<7,>=6.0
+Requires-Dist: sentence-transformers<4,>=2.7.0
+Requires-Dist: numpy<3,>=1.24
+Provides-Extra: test
+Requires-Dist: pytest<9,>=7.4; extra == "test"
+Requires-Dist: pytest-asyncio<2,>=0.23; extra == "test"
+Provides-Extra: mcp
+Requires-Dist: mcp[cli]<2,>=1.0; extra == "mcp"
+Dynamic: license-file
+
+# Hexus 🧠
+[![Tests](https://github.com/codenamekt/hexus/actions/workflows/ci.yml/badge.svg)](https://github.com/codenamekt/hexus/actions/workflows/ci.yml) [![PyPI version](https://badge.fury.io/py/hexus.svg)](https://badge.fury.io/py/hexus)
+### Postgres-Powered Vector Memory for the Agentic Age
+
+**Postgres + hexus memory substrate for [hermes-agent](https://github.com/NousResearch/hermes-agent) AND a standalone Model Context Protocol (MCP) server for any client (Claude Desktop, Cursor, fleet agents, etc.).** 
+
+```mermaid
+graph TD
+    classDef default fill:#1f2937,stroke:#374151,stroke-width:1px,color:#f3f4f6;
+    classDef highlight fill:#3b82f6,stroke:#1d4ed8,stroke-width:2px,color:#ffffff;
+    classDef db fill:#059669,stroke:#047857,stroke-width:2px,color:#ffffff;
+
+    subgraph Clients ["Integration Clients"]
+        Minions["Hermes Agent Minions<br/>(Header: X-Hermes-Session-Key)"]
+        Claude["Claude Desktop<br/>(stdio MCP)"]
+        Cursor["Cursor Editor<br/>(stdio MCP)"]
+        Custom["Custom Agents<br/>(HTTP MCP)"]
+    end
+
+    subgraph Hexus ["Hexus (Single Process, Shared Embedder)"]
+        Plugin["Hermes Plugin<br/>(hexus/__init__.py)"]
+        Server["MCP Server<br/>(mcp_server)"]
+        Embedder["LocalBertEmbedder<br/>(MiniLM-L6-v2)"]:::highlight
+        Store["MemoryStore<br/>(psycopg pool)"]
+    end
+
+    DB[("PostgreSQL 16 + pgvector<br/>(memory_entries & conversations)")]:::db
+
+    %% Connections
+    Minions -->|X-Hermes-Session-Key| Plugin
+    Claude -->|stdio| Server
+    Cursor -->|stdio| Server
+    Custom -->|HTTP| Server
+
+    Plugin --> Embedder
+    Server --> Embedder
+    Plugin --> Store
+    Server --> Store
+
+    Store --> DB
+```
+
+---
+
+## 🚨 The "Memory Crisis" (And Why Hexus Rocks 🎸)
+
+If you've ever tried running a team of cooperating agents, you've probably hit one of these roadblocks. Here's why Hexus exists and how it changes the game:
+
+*   **The Stomping Minions 🐘**: Say goodbye to local markdown files that get overwritten when you run multiple agents. Hexus gives every minion a clean, scoped memory space ("themes"). Your marketing agent's notes won't contaminate your trading agent's data!
+*   **Pure Vector Speed (No LLM in the Hot Path!) ⚡**: Embedding search should be pure vector math! We use a purely local BERT model. Zero cloud calls, zero LLMs in the hot path, absolute privacy, and *way* faster performance.
+*   **Ditch the Cloud Monoliths ☁️**: Other memory providers require paid cloud services and route every read/write through an LLM. Not us. Hexus uses your existing Postgres + `pgvector`. Keep it simple, keep it fast!
+*   **Storage Layer AND Memory Model 📦**: Hexus acts as a rock-solid storage backbone *and* an intelligent memory model for a fleet of cooperating agents, keeping everything centralized, searchable, and clean.
+*   **Standalone Plugin Power 🧩**: Why a standalone plugin? So you can just drop it in and go! No waiting for upstream PRs in the main repositories.
+
+## 🌪️ Getting Started (Installation is a breeze!)
+
+Ready to try it out? You can get up and running in a snap.
+
+### Option 1: Hermes Plugin (via pip)
+If you're integrating directly into a Hermes agent, you can grab it from pip:
+
+```bash
+pip install hexus
+```
+*Note: Once installed, just point Hermes to it! You can also just drop the `hexus` module files straight into your `~/.hermes/plugins/hexus/` directory. Hermes's discovery system will automatically pick it up and initialize it on startup!*
+
+### Option 2: Docker & MCP Server (Claude, Cursor, etc.)
+The easiest way to run the standalone MCP server is via Docker (GHCR). 
+
+> **Note:** The Docker MCP server requires a running PostgreSQL database with `pgvector` enabled. You can reference or use our provided `docker/compose.yml` file as a quick example to spin one up!
+
+```bash
+# Run the MCP server via HTTP streamable transport on port 8000
+docker run -d --name hexus -p 8000:8000 ghcr.io/codenamekt/hexus:latest
+```
+
+**Using it with Claude Code / Claude Desktop:**
+If you want to plug Hexus straight into your Claude `claude_desktop_config.json` via standard `stdio`, you can add this block to seamlessly run the Docker image in the background:
+
+```jsonc
+{
+  "mcpServers": {
+    "hexus": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-e",
+        "HEXUS_DSN=dbname=hermes_memory user=postgres host=host.docker.internal",
+        "ghcr.io/codenamekt/hexus:latest",
+        "hexus-mcp",
+        "serve",
+        "--transport",
+        "stdio"
+      ]
+    }
+  }
+}
+```
+
+## 🏎️ Look at This! Ridiculously Fast Benchmarks
+We believe in speed. Check out these actual benchmarks running on a basic CPU (no GPU needed!):
+
+*   **Single Embed Latency**: `7.4 ms`
+*   **Batch Embed Throughput**: `1,486 items/sec` (batch size 32)
+*   **Recall Latency (Top 5)**: `2.0 ms`
+
+Wanna run these yourself? Check out the full [BENCHMARK.md](docs/BENCHMARK.md) to see how!
+
+## ✨ Wait... There's More! (Features)
+
+*   **Two Integration Paths, One Shared Store**: Use it as a Hermes plugin, OR run it as a standalone Model Context Protocol (MCP) server for Claude Desktop, Cursor, and custom agents.
+*   **Built-in Power-Ups**: Hybrid search (BM25 + vector), temporal decay, TTL/memory forgetfulness, entity tagging, and conversation summaries.
+*   **Potato-Friendly**: Runs entirely local on a CPU (e.g. an old Intel NUC or mini PC).
+
+## 🕳️ Digging Deeper
+
+Looking for the nitty-gritty details? We moved the heavy technical stuff into their own docs so you can get straight to the code:
+
+*   📖 [Technical Details & Configuration](docs/TECHNICAL_DETAILS.md) - Admin DB commands, schemas, hooks, and MCP configuration.
+*   🗺️ [Roadmap](docs/ROADMAP.md) - See where we've been and what wild features are coming next.
+*   🔙 [Rollback Guide](docs/ROLLBACK.md) - In case you change your mind (but you won't!).
+
+---
+*License: [BSD 3-Clause](LICENSE)*

hexus-0.9.0/README.md

@@ -0,0 +1,126 @@
+# Hexus 🧠
+[![Tests](https://github.com/codenamekt/hexus/actions/workflows/ci.yml/badge.svg)](https://github.com/codenamekt/hexus/actions/workflows/ci.yml) [![PyPI version](https://badge.fury.io/py/hexus.svg)](https://badge.fury.io/py/hexus)
+### Postgres-Powered Vector Memory for the Agentic Age
+
+**Postgres + hexus memory substrate for [hermes-agent](https://github.com/NousResearch/hermes-agent) AND a standalone Model Context Protocol (MCP) server for any client (Claude Desktop, Cursor, fleet agents, etc.).** 
+
+```mermaid
+graph TD
+    classDef default fill:#1f2937,stroke:#374151,stroke-width:1px,color:#f3f4f6;
+    classDef highlight fill:#3b82f6,stroke:#1d4ed8,stroke-width:2px,color:#ffffff;
+    classDef db fill:#059669,stroke:#047857,stroke-width:2px,color:#ffffff;
+
+    subgraph Clients ["Integration Clients"]
+        Minions["Hermes Agent Minions<br/>(Header: X-Hermes-Session-Key)"]
+        Claude["Claude Desktop<br/>(stdio MCP)"]
+        Cursor["Cursor Editor<br/>(stdio MCP)"]
+        Custom["Custom Agents<br/>(HTTP MCP)"]
+    end
+
+    subgraph Hexus ["Hexus (Single Process, Shared Embedder)"]
+        Plugin["Hermes Plugin<br/>(hexus/__init__.py)"]
+        Server["MCP Server<br/>(mcp_server)"]
+        Embedder["LocalBertEmbedder<br/>(MiniLM-L6-v2)"]:::highlight
+        Store["MemoryStore<br/>(psycopg pool)"]
+    end
+
+    DB[("PostgreSQL 16 + pgvector<br/>(memory_entries & conversations)")]:::db
+
+    %% Connections
+    Minions -->|X-Hermes-Session-Key| Plugin
+    Claude -->|stdio| Server
+    Cursor -->|stdio| Server
+    Custom -->|HTTP| Server
+
+    Plugin --> Embedder
+    Server --> Embedder
+    Plugin --> Store
+    Server --> Store
+
+    Store --> DB
+```
+
+---
+
+## 🚨 The "Memory Crisis" (And Why Hexus Rocks 🎸)
+
+If you've ever tried running a team of cooperating agents, you've probably hit one of these roadblocks. Here's why Hexus exists and how it changes the game:
+
+*   **The Stomping Minions 🐘**: Say goodbye to local markdown files that get overwritten when you run multiple agents. Hexus gives every minion a clean, scoped memory space ("themes"). Your marketing agent's notes won't contaminate your trading agent's data!
+*   **Pure Vector Speed (No LLM in the Hot Path!) ⚡**: Embedding search should be pure vector math! We use a purely local BERT model. Zero cloud calls, zero LLMs in the hot path, absolute privacy, and *way* faster performance.
+*   **Ditch the Cloud Monoliths ☁️**: Other memory providers require paid cloud services and route every read/write through an LLM. Not us. Hexus uses your existing Postgres + `pgvector`. Keep it simple, keep it fast!
+*   **Storage Layer AND Memory Model 📦**: Hexus acts as a rock-solid storage backbone *and* an intelligent memory model for a fleet of cooperating agents, keeping everything centralized, searchable, and clean.
+*   **Standalone Plugin Power 🧩**: Why a standalone plugin? So you can just drop it in and go! No waiting for upstream PRs in the main repositories.
+
+## 🌪️ Getting Started (Installation is a breeze!)
+
+Ready to try it out? You can get up and running in a snap.
+
+### Option 1: Hermes Plugin (via pip)
+If you're integrating directly into a Hermes agent, you can grab it from pip:
+
+```bash
+pip install hexus
+```
+*Note: Once installed, just point Hermes to it! You can also just drop the `hexus` module files straight into your `~/.hermes/plugins/hexus/` directory. Hermes's discovery system will automatically pick it up and initialize it on startup!*
+
+### Option 2: Docker & MCP Server (Claude, Cursor, etc.)
+The easiest way to run the standalone MCP server is via Docker (GHCR). 
+
+> **Note:** The Docker MCP server requires a running PostgreSQL database with `pgvector` enabled. You can reference or use our provided `docker/compose.yml` file as a quick example to spin one up!
+
+```bash
+# Run the MCP server via HTTP streamable transport on port 8000
+docker run -d --name hexus -p 8000:8000 ghcr.io/codenamekt/hexus:latest
+```
+
+**Using it with Claude Code / Claude Desktop:**
+If you want to plug Hexus straight into your Claude `claude_desktop_config.json` via standard `stdio`, you can add this block to seamlessly run the Docker image in the background:
+
+```jsonc
+{
+  "mcpServers": {
+    "hexus": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-e",
+        "HEXUS_DSN=dbname=hermes_memory user=postgres host=host.docker.internal",
+        "ghcr.io/codenamekt/hexus:latest",
+        "hexus-mcp",
+        "serve",
+        "--transport",
+        "stdio"
+      ]
+    }
+  }
+}
+```
+
+## 🏎️ Look at This! Ridiculously Fast Benchmarks
+We believe in speed. Check out these actual benchmarks running on a basic CPU (no GPU needed!):
+
+*   **Single Embed Latency**: `7.4 ms`
+*   **Batch Embed Throughput**: `1,486 items/sec` (batch size 32)
+*   **Recall Latency (Top 5)**: `2.0 ms`
+
+Wanna run these yourself? Check out the full [BENCHMARK.md](docs/BENCHMARK.md) to see how!
+
+## ✨ Wait... There's More! (Features)
+
+*   **Two Integration Paths, One Shared Store**: Use it as a Hermes plugin, OR run it as a standalone Model Context Protocol (MCP) server for Claude Desktop, Cursor, and custom agents.
+*   **Built-in Power-Ups**: Hybrid search (BM25 + vector), temporal decay, TTL/memory forgetfulness, entity tagging, and conversation summaries.
+*   **Potato-Friendly**: Runs entirely local on a CPU (e.g. an old Intel NUC or mini PC).
+
+## 🕳️ Digging Deeper
+
+Looking for the nitty-gritty details? We moved the heavy technical stuff into their own docs so you can get straight to the code:
+
+*   📖 [Technical Details & Configuration](docs/TECHNICAL_DETAILS.md) - Admin DB commands, schemas, hooks, and MCP configuration.
+*   🗺️ [Roadmap](docs/ROADMAP.md) - See where we've been and what wild features are coming next.
+*   🔙 [Rollback Guide](docs/ROLLBACK.md) - In case you change your mind (but you won't!).
+
+---
+*License: [BSD 3-Clause](LICENSE)*