hermes-next 0.1.0__tar.gz

hermes_next-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,64 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install ruff
+        run: pip install ruff
+      - name: Lint
+        run: ruff check hermes_next/ tests/
+      - name: Format check
+        run: ruff format --check hermes_next/ tests/ || true
+
+  type-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: |
+          pip install mypy
+          pip install -e "."
+      - name: Type check
+        run: mypy hermes_next/ --ignore-missing-imports --follow-imports=skip || true
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+
+      - name: Install package
+        run: |
+          uv pip install --system -e "."
+          uv pip install --system pytest pytest-asyncio httpx numpy
+
+      - name: Test
+        run: pytest tests/ -v -k "not integration" --timeout=30
+        env:
+          HERMES_NEXT_OV_URL: ${{ secrets.HERMES_NEXT_OV_URL || 'http://localhost:1933' }}

hermes_next-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,31 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install hatchling
+
+      - name: Build package
+        run: |
+          python -m hatchling build
+          ls -la dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

hermes_next-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# Cache
+*.db
+*.db-wal
+*.db-shm
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Environment
+.env
+.env.*
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Test artifacts
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Project
+*.lock

hermes_next-0.1.0/LICENSE

@@ -0,0 +1,17 @@
+GNU AFFERO GENERAL PUBLIC LICENSE
+Version 3, 19 November 2007
+
+Copyright (C) 2024 jigeagent
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.

hermes_next-0.1.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: hermes-next
+Version: 0.1.0
+Summary: Next-generation memory provider for Hermes Agent — fusing OpenViking vector storage with MemOS cognitive engine
+Project-URL: Homepage, https://github.com/jigeagent/hermes-next
+Project-URL: Repository, https://github.com/jigeagent/hermes-next.git
+Project-URL: Documentation, https://github.com/jigeagent/hermes-next#readme
+Project-URL: Issues, https://github.com/jigeagent/hermes-next/issues
+Author-email: jigeagent <oss@jigeagent.ai>
+License: AGPL-3.0-or-later
+License-File: LICENSE
+Keywords: cognitive,hermes-agent,memory,memos,openviking,rag,vector-search
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: httpx
+Requires-Dist: numpy
+Requires-Dist: openviking>=0.3.22
+Description-Content-Type: text/markdown
+
+# Hermes Next
+
+**Next-generation memory provider for Hermes Agent.**
+
+Hermes Next fuses [OpenViking](https://github.com/bytedance/openviking) vector storage with a Python-native [MemOS](https://github.com/memtensor/memos) cognitive engine, giving Hermes Agent agents persistent,结构化记忆能力。
+
+## Features
+
+- **OpenViking Backend** — Long-term vector storage, semantic retrieval, session management
+- **MemOS Cognitive Pipeline** — L1 Trace capture → reward backpropagation → L2 Policy induction → L3 World Model → Skill crystallization
+- **Python Native** — Zero bridging overhead, runs in-process
+- **Local SQLite Cache** — FTS5 full-text search + numpy-based cosine similarity, zero dependencies beyond stdlib
+- **Fusion Retrieval** — 6-step pipeline combining semantic search, full-text search, policy matching, timeline, recency boost, and MMR diversification
+
+## Installation
+
+```bash
+pip install hermes-next
+```
+
+Requires Python 3.10+ and a running OpenViking server (v0.3.22+).
+
+## Configuration
+
+Create a `hermes-next.yaml` in your config directory:
+
+```yaml
+openviking:
+  base_url: "http://localhost:1933"
+  api_key: null
+
+cache:
+  path: "~/.hermes-next/cache.db"
+  enable_fts: true
+
+agent:
+  name: "default"
+```
+
+Or set environment variables:
+
+```bash
+export HERMES_NEXT_OV_URL="http://localhost:1933"
+export HERMES_NEXT_CACHE_PATH="~/.hermes-next/cache.db"
+```
+
+## Usage with Hermes Agent
+
+```python
+from hermes_next import HermesNextProvider
+
+provider = HermesNextProvider()
+provider.initialize(session_id="my-session")
+
+# The provider handles prefetching, storage, and retrieval automatically
+context = provider.prefetch("What did we discuss about RAG?")
+print(context)
+```
+
+Or via CLI:
+
+```bash
+hermes agent --memory-provider hermes-next
+```
+
+## Tools
+
+The provider exposes these tools to the agent:
+
+| Tool | Description |
+|------|-------------|
+| `memos_search(query, k)` | Semantic search across traces |
+| `memos_get(trace_id)` | Read a specific trace |
+| `memos_timeline(limit)` | Recent activity timeline |
+
+## Project Structure
+
+```
+hermes-next/
+├── hermes_next/
+│   ├── ov/            # OpenViking REST client
+│   ├── memos/         # MemOS cognitive engine
+│   ├── cache/         # SQLite local cache
+│   └── retrieval/     # Fusion retrieval pipeline
+├── tests/
+└── plugin.yaml        # Hermes plugin manifest
+```
+
+## License
+
+AGPL-3.0 — This project is a derivative of OpenViking (AGPL-3.0).

hermes_next-0.1.0/README.md

@@ -0,0 +1,91 @@
+# Hermes Next
+
+**Next-generation memory provider for Hermes Agent.**
+
+Hermes Next fuses [OpenViking](https://github.com/bytedance/openviking) vector storage with a Python-native [MemOS](https://github.com/memtensor/memos) cognitive engine, giving Hermes Agent agents persistent,结构化记忆能力。
+
+## Features
+
+- **OpenViking Backend** — Long-term vector storage, semantic retrieval, session management
+- **MemOS Cognitive Pipeline** — L1 Trace capture → reward backpropagation → L2 Policy induction → L3 World Model → Skill crystallization
+- **Python Native** — Zero bridging overhead, runs in-process
+- **Local SQLite Cache** — FTS5 full-text search + numpy-based cosine similarity, zero dependencies beyond stdlib
+- **Fusion Retrieval** — 6-step pipeline combining semantic search, full-text search, policy matching, timeline, recency boost, and MMR diversification
+
+## Installation
+
+```bash
+pip install hermes-next
+```
+
+Requires Python 3.10+ and a running OpenViking server (v0.3.22+).
+
+## Configuration
+
+Create a `hermes-next.yaml` in your config directory:
+
+```yaml
+openviking:
+  base_url: "http://localhost:1933"
+  api_key: null
+
+cache:
+  path: "~/.hermes-next/cache.db"
+  enable_fts: true
+
+agent:
+  name: "default"
+```
+
+Or set environment variables:
+
+```bash
+export HERMES_NEXT_OV_URL="http://localhost:1933"
+export HERMES_NEXT_CACHE_PATH="~/.hermes-next/cache.db"
+```
+
+## Usage with Hermes Agent
+
+```python
+from hermes_next import HermesNextProvider
+
+provider = HermesNextProvider()
+provider.initialize(session_id="my-session")
+
+# The provider handles prefetching, storage, and retrieval automatically
+context = provider.prefetch("What did we discuss about RAG?")
+print(context)
+```
+
+Or via CLI:
+
+```bash
+hermes agent --memory-provider hermes-next
+```
+
+## Tools
+
+The provider exposes these tools to the agent:
+
+| Tool | Description |
+|------|-------------|
+| `memos_search(query, k)` | Semantic search across traces |
+| `memos_get(trace_id)` | Read a specific trace |
+| `memos_timeline(limit)` | Recent activity timeline |
+
+## Project Structure
+
+```
+hermes-next/
+├── hermes_next/
+│   ├── ov/            # OpenViking REST client
+│   ├── memos/         # MemOS cognitive engine
+│   ├── cache/         # SQLite local cache
+│   └── retrieval/     # Fusion retrieval pipeline
+├── tests/
+└── plugin.yaml        # Hermes plugin manifest
+```
+
+## License
+
+AGPL-3.0 — This project is a derivative of OpenViking (AGPL-3.0).

hermes_next-0.1.0/hermes_next/__init__.py

@@ -0,0 +1,11 @@
+"""Hermes Next — Next-generation memory provider for Hermes Agent."""
+
+from hermes_next.provider import HermesNextProvider
+
+__version__ = "0.1.0"
+__all__ = ["HermesNextProvider", "register"]
+
+
+def register():
+    """Plugin entry point — returns the provider class for Hermes Agent discovery."""
+    return HermesNextProvider

hermes_next-0.1.0/hermes_next/cache/__init__.py

@@ -0,0 +1 @@
+"""SQLite local cache layer."""

hermes_next-0.1.0/hermes_next/cache/connection.py

@@ -0,0 +1,100 @@
+"""SQLite connection management with performance optimizations."""
+
+from __future__ import annotations
+
+import sqlite3
+import threading
+from pathlib import Path
+from typing import Optional
+
+
+# Shared statement cache across threads
+_STMT_CACHE: dict[str, sqlite3.Cursor] = {}
+
+
+class CacheConnection:
+    """Thread-safe SQLite connection manager with performance tuning.
+
+    Optimizations:
+    - WAL mode for concurrent reads
+    - 64MB cache for hot data
+    - memory-mapped I/O (256MB)
+    - Lazy pragma initialization (deferred until first query)
+    """
+
+    def __init__(self, db_path: str, wal_mode: bool = True):
+        self._db_path = str(Path(db_path).expanduser())
+        self._wal = wal_mode
+        self._local = threading.local()
+        self._lock = threading.Lock()
+        self._initialized = False
+
+        # Ensure parent directory exists
+        Path(self._db_path).parent.mkdir(parents=True, exist_ok=True)
+
+    def _ensure_init(self) -> None:
+        """Apply performance pragmas once per connection."""
+        if self._initialized:
+            return
+        conn = self._get_conn_raw()
+        if self._wal:
+            conn.execute("PRAGMA journal_mode=WAL")
+        conn.executescript("""
+            PRAGMA synchronous=NORMAL;
+            PRAGMA foreign_keys=ON;
+            PRAGMA cache_size=-65536;
+            PRAGMA mmap_size=268435456;
+            PRAGMA temp_store=MEMORY;
+            PRAGMA busy_timeout=5000;
+        """)
+        self._initialized = True
+
+    def _get_conn_raw(self) -> sqlite3.Connection:
+        """Create a raw connection without pragma setup."""
+        if not hasattr(self._local, "conn") or self._local.conn is None:
+            conn = sqlite3.connect(
+                self._db_path,
+                check_same_thread=False,
+                isolation_level=None,  # autocommit mode
+            )
+            conn.row_factory = sqlite3.Row
+            self._local.conn = conn
+        return self._local.conn
+
+    @property
+    def conn(self) -> sqlite3.Connection:
+        self._ensure_init()
+        return self._get_conn_raw()
+
+    def execute(self, sql: str, params: tuple = ()) -> sqlite3.Cursor:
+        """Execute with automatic pragma init."""
+        self._ensure_init()
+        return self._get_conn_raw().execute(sql, params)
+
+    def executemany(self, sql: str, params: list[tuple]) -> sqlite3.Cursor:
+        """Batch execute with automatic pragma init."""
+        self._ensure_init()
+        return self._get_conn_raw().executemany(sql, params)
+
+    def close(self) -> None:
+        """Close the connection for the current thread."""
+        if hasattr(self._local, "conn") and self._local.conn is not None:
+            try:
+                self._local.conn.execute("PRAGMA optimize")
+            except Exception:
+                pass
+            self._local.conn.close()
+            self._local.conn = None
+            self._initialized = False
+
+    def close_all(self) -> None:
+        """Force close via lock (use sparingly)."""
+        with self._lock:
+            if hasattr(self._local, "conn") and self._local.conn is not None:
+                try:
+                    self._local.conn.execute("PRAGMA optimize")
+                except Exception:
+                    pass
+                self._local.conn.close()
+                self._local.conn = None
+                self._initialized = False

hermes_next-0.1.0/hermes_next/cache/policies.py

@@ -0,0 +1,94 @@
+"""Policy repository — local SQLite CRUD for policies."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Optional
+
+from hermes_next.cache.connection import CacheConnection
+from hermes_next.cache.schema import ensure_schema
+from hermes_next.memos.types import PolicyRow
+
+
+class PolicyRepository:
+    """Persist and query policies locally."""
+
+    def __init__(self, cache: CacheConnection):
+        self._cache = cache
+        ensure_schema(cache)
+
+    def insert(self, policy: PolicyRow) -> None:
+        """Insert a policy into local cache."""
+        conn = self._cache.conn
+        conn.execute(
+            """
+            INSERT OR REPLACE INTO policies
+                (id, name, description, trigger_pattern, action_template,
+                 embedding, confidence, activation_count, source_trace_ids,
+                 metadata, created_at, synced)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            (
+                policy.id,
+                policy.name,
+                policy.description,
+                policy.trigger_pattern,
+                policy.action_template,
+                json.dumps(policy.embedding) if policy.embedding else None,
+                policy.confidence,
+                policy.activation_count,
+                json.dumps(policy.source_trace_ids, ensure_ascii=False),
+                json.dumps(policy.metadata, ensure_ascii=False, default=str),
+                policy.created_at,
+                0,
+            ),
+        )
+        conn.commit()
+
+    def get(self, policy_id: str) -> Optional[PolicyRow]:
+        """Get a policy by ID."""
+        row = self._cache.conn.execute(
+            "SELECT * FROM policies WHERE id = ?", (policy_id,)
+        ).fetchone()
+        if row is None:
+            return None
+        return self._row_to_policy(row)
+
+    def list_active(self, min_confidence: float = 0.3, limit: int = 20) -> list[PolicyRow]:
+        """List policies with confidence above threshold."""
+        rows = self._cache.conn.execute(
+            "SELECT * FROM policies WHERE confidence >= ? ORDER BY confidence DESC LIMIT ?",
+            (min_confidence, limit),
+        ).fetchall()
+        return [self._row_to_policy(r) for r in rows]
+
+    def increment_activation(self, policy_id: str) -> None:
+        """Increment activation count for a policy."""
+        self._cache.conn.execute(
+            "UPDATE policies SET activation_count = activation_count + 1 WHERE id = ?",
+            (policy_id,),
+        )
+        self._cache.conn.commit()
+
+    def count(self) -> int:
+        """Total policy count."""
+        row = self._cache.conn.execute("SELECT COUNT(*) as cnt FROM policies").fetchone()
+        return row["cnt"] if row else 0
+
+    @staticmethod
+    def _row_to_policy(row: Any) -> PolicyRow:
+        return PolicyRow(
+            id=row["id"],
+            name=row["name"],
+            description=row["description"],
+            trigger_pattern=row["trigger_pattern"],
+            action_template=row["action_template"],
+            embedding=json.loads(row["embedding"]) if row["embedding"] else None,
+            confidence=row["confidence"],
+            activation_count=row["activation_count"],
+            source_trace_ids=json.loads(row["source_trace_ids"])
+            if isinstance(row["source_trace_ids"], str)
+            else [],
+            metadata=json.loads(row["metadata"]) if isinstance(row["metadata"], str) else {},
+            created_at=row["created_at"],
+        )

hermes_next-0.1.0/hermes_next/cache/schema.py

@@ -0,0 +1,100 @@
+"""SQLite schema — traces, policies, skills tables with FTS5."""
+
+from __future__ import annotations
+
+from hermes_next.cache.connection import CacheConnection
+
+
+def ensure_schema(conn_or_cache: CacheConnection) -> None:
+    """Create all tables and indexes if they don't exist."""
+    conn = conn_or_cache.conn if isinstance(conn_or_cache, CacheConnection) else conn_or_cache
+
+    conn.executescript("""
+        CREATE TABLE IF NOT EXISTS traces (
+            id          TEXT PRIMARY KEY,
+            session_id  TEXT NOT NULL,
+            turn_index  INTEGER NOT NULL DEFAULT 0,
+            user_content TEXT NOT NULL,
+            assistant_content TEXT NOT NULL DEFAULT '',
+            embedding   BLOB,
+            reward      REAL NOT NULL DEFAULT 0.0,
+            tags        TEXT DEFAULT '',
+            metadata    TEXT DEFAULT '{}',
+            created_at  TEXT NOT NULL,
+            synced      INTEGER NOT NULL DEFAULT 0
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_traces_session
+            ON traces(session_id);
+        CREATE INDEX IF NOT EXISTS idx_traces_created
+            ON traces(created_at);
+        CREATE INDEX IF NOT EXISTS idx_traces_synced
+            ON traces(synced);
+
+        CREATE TABLE IF NOT EXISTS policies (
+            id              TEXT PRIMARY KEY,
+            name            TEXT NOT NULL,
+            description     TEXT NOT NULL DEFAULT '',
+            trigger_pattern TEXT NOT NULL DEFAULT '',
+            action_template TEXT NOT NULL DEFAULT '',
+            embedding       BLOB,
+            confidence      REAL NOT NULL DEFAULT 0.0,
+            activation_count INTEGER NOT NULL DEFAULT 0,
+            source_trace_ids TEXT DEFAULT '[]',
+            metadata        TEXT DEFAULT '{}',
+            created_at      TEXT NOT NULL,
+            synced          INTEGER NOT NULL DEFAULT 0
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_policies_confidence
+            ON policies(confidence DESC);
+
+        CREATE TABLE IF NOT EXISTS skills (
+            name            TEXT PRIMARY KEY,
+            description     TEXT NOT NULL DEFAULT '',
+            usage_guide     TEXT NOT NULL DEFAULT '',
+            source_policy_ids TEXT DEFAULT '[]',
+            version         INTEGER NOT NULL DEFAULT 1,
+            metadata        TEXT DEFAULT '{}',
+            created_at      TEXT NOT NULL
+        );
+
+        CREATE VIRTUAL TABLE IF NOT EXISTS traces_fts
+            USING fts5(
+                user_content,
+                assistant_content,
+                tags,
+                content='traces',
+                content_rowid='rowid'
+            );
+
+        CREATE TRIGGER IF NOT EXISTS traces_ai AFTER INSERT ON traces BEGIN
+            INSERT INTO traces_fts(rowid, user_content, assistant_content, tags)
+            VALUES (new.rowid, new.user_content, new.assistant_content, new.tags);
+        END;
+
+        CREATE TRIGGER IF NOT EXISTS traces_ad AFTER DELETE ON traces BEGIN
+            INSERT INTO traces_fts(traces_fts, rowid, user_content, assistant_content, tags)
+            VALUES ('delete', old.rowid, old.user_content, old.assistant_content, old.tags);
+        END;
+
+        CREATE TRIGGER IF NOT EXISTS traces_au AFTER UPDATE ON traces BEGIN
+            INSERT INTO traces_fts(traces_fts, rowid, user_content, assistant_content, tags)
+            VALUES ('delete', old.rowid, old.user_content, old.assistant_content, old.tags);
+            INSERT INTO traces_fts(rowid, user_content, assistant_content, tags)
+            VALUES (new.rowid, new.user_content, new.assistant_content, new.tags);
+        END;
+    """)
+    conn.commit()
+
+
+def drop_schema(conn_or_cache: CacheConnection) -> None:
+    """Drop all tables (for testing)."""
+    conn = conn_or_cache.conn if isinstance(conn_or_cache, CacheConnection) else conn_or_cache
+    conn.executescript("""
+        DROP TABLE IF EXISTS traces_fts;
+        DROP TABLE IF EXISTS skills;
+        DROP TABLE IF EXISTS policies;
+        DROP TABLE IF EXISTS traces;
+    """)
+    conn.commit()