upstash-hermes-memory 0.1.0__tar.gz

upstash_hermes_memory-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+node_modules
+dist
+coverage
+*.log
+.DS_Store
+.turbo
+.vercel
+.env
+.env.*
+!.env.example
+*.tsbuildinfo
+.vscode
+.idea
+.venv
+__pycache__
+*.egg-info
+.pytest_cache
+.ruff_cache

upstash_hermes_memory-0.1.0/CHANGELOG.md

@@ -0,0 +1,7 @@
+# upstash-hermes-memory
+
+## 0.1.0
+
+### Minor Changes
+
+- 6269e3b: First release: an Upstash Redis memory provider for Hermes Agent. It recalls related memories into each turn, saves every session as a searchable transcript, mirrors the built-in `memory` tool, and gives the model `upstash_memory_save` / `_search` / `_forget` and `upstash_chat_search`. It reads and writes the same keys and Redis Search indexes as `AgentMemory` and `ChatHistory` in `@upstash/agentkit-sdk`, so memories are shared with AgentKit apps on the same database.

upstash_hermes_memory-0.1.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.5
+Name: upstash-hermes-memory
+Version: 0.1.0
+Summary: Upstash Redis memory provider for Hermes Agent: long-term memory, searchable chat history and recall on Redis Search, with no separate vector database.
+Project-URL: Homepage, https://github.com/upstash/agentkit
+Project-URL: Repository, https://github.com/upstash/agentkit
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: upstash-redis>=1.8.0
+Description-Content-Type: text/markdown
+
+# upstash-hermes-memory
+
+An Upstash Redis memory provider for [Hermes Agent](https://hermes-agent.nousresearch.com), built on
+the same Redis Search layout as `@upstash/agentkit-sdk`'s `AgentMemory` and `ChatHistory`. A memory
+your AI SDK app saves is recalled by your Hermes agent, and the other way round.
+
+## What it does in Hermes
+
+- **Recall:** before each turn, the memories closest to the user's message are added to the prompt.
+- **Chat history:** after each turn, the session's transcript is saved as a searchable document.
+- **Mirroring:** facts the built-in `memory` tool adds are also saved to Redis.
+- **Tools:** `upstash_memory_save`, `upstash_memory_search`, `upstash_memory_forget` and
+  `upstash_chat_search` (search past conversations).
+
+Subagents, cron jobs and context flushes can read memory but never write it.
+
+## Setup
+
+```bash
+# into the Python environment Hermes runs in
+pip install upstash-hermes-memory
+```
+
+Then select it in Hermes's `config.yaml`:
+
+```yaml
+memory:
+  provider: upstash
+```
+
+And give it a database, in your environment or `~/.hermes/.env` (`hermes memory setup` asks for
+these):
+
+| Variable | |
+| --- | --- |
+| `UPSTASH_REDIS_REST_URL`, `UPSTASH_REDIS_REST_TOKEN` | Required. From the [Upstash console](https://console.upstash.com/redis). |
+| `UPSTASH_HERMES_USER_ID` | Whose memories these are. Defaults to the gateway user, then the Hermes profile name, then `default`. |
+| `UPSTASH_HERMES_MEMORY_PREFIX`, `UPSTASH_HERMES_CHAT_PREFIX` | Key prefixes. Default `agentkit:memory` and `agentkit:chat`, the TS SDK's defaults, so the two share memories. |
+
+## Redis layout
+
+| | Key | Index |
+| --- | --- | --- |
+| Memory | `agentkit:memory:<user>:<id>` → JSON `{text, userId, createdAt, ...metadata}` | `agentkit_memory` (`text`, `userId`) |
+| Chat | `agentkit:chat:<user>:<session>` → JSON `{userId, sessionId, userMessages, modelMessages, messages, createdAt, updatedAt}` | `agentkit_chat` |
+
+User and session ids are used as they are, so the same id reads the same keys from Hermes and the
+TS SDK. Like the TS SDK, the provider refuses a user id with `:` (the key separator), and keeps no
+transcript for a session id with one. Indexes are created on first use. `AgentMemory` and `ChatHistory` are importable on their own for
+use outside Hermes.
+
+## Development
+
+```bash
+uv sync --all-packages && pnpm py:lint && pnpm py:test   # Redis tests need UPSTASH_REDIS_REST_* set
+uv run python python/hermes-memory/e2e/hermes_e2e.py     # a real Hermes session, needs OPENAI_API_KEY
+```
+
+The e2e script installs the package into a temporary directory and runs Hermes with a temporary
+`HERMES_HOME`, so your own Hermes install is not touched. Hermes's built-in memory is turned off
+there. One session saves two facts; a fresh session started right after must name them without
+calling any tool (checked in Hermes's `state.db`), so they can only come from the automatic recall;
+and a control session as another user must not know them. The script then checks the keys and
+transcripts in Redis (and, if `packages/sdk` is built, that the TS `AgentMemory` recalls them too)
+before cleaning up.

upstash_hermes_memory-0.1.0/README.md

@@ -0,0 +1,65 @@
+# upstash-hermes-memory
+
+An Upstash Redis memory provider for [Hermes Agent](https://hermes-agent.nousresearch.com), built on
+the same Redis Search layout as `@upstash/agentkit-sdk`'s `AgentMemory` and `ChatHistory`. A memory
+your AI SDK app saves is recalled by your Hermes agent, and the other way round.
+
+## What it does in Hermes
+
+- **Recall:** before each turn, the memories closest to the user's message are added to the prompt.
+- **Chat history:** after each turn, the session's transcript is saved as a searchable document.
+- **Mirroring:** facts the built-in `memory` tool adds are also saved to Redis.
+- **Tools:** `upstash_memory_save`, `upstash_memory_search`, `upstash_memory_forget` and
+  `upstash_chat_search` (search past conversations).
+
+Subagents, cron jobs and context flushes can read memory but never write it.
+
+## Setup
+
+```bash
+# into the Python environment Hermes runs in
+pip install upstash-hermes-memory
+```
+
+Then select it in Hermes's `config.yaml`:
+
+```yaml
+memory:
+  provider: upstash
+```
+
+And give it a database, in your environment or `~/.hermes/.env` (`hermes memory setup` asks for
+these):
+
+| Variable | |
+| --- | --- |
+| `UPSTASH_REDIS_REST_URL`, `UPSTASH_REDIS_REST_TOKEN` | Required. From the [Upstash console](https://console.upstash.com/redis). |
+| `UPSTASH_HERMES_USER_ID` | Whose memories these are. Defaults to the gateway user, then the Hermes profile name, then `default`. |
+| `UPSTASH_HERMES_MEMORY_PREFIX`, `UPSTASH_HERMES_CHAT_PREFIX` | Key prefixes. Default `agentkit:memory` and `agentkit:chat`, the TS SDK's defaults, so the two share memories. |
+
+## Redis layout
+
+| | Key | Index |
+| --- | --- | --- |
+| Memory | `agentkit:memory:<user>:<id>` → JSON `{text, userId, createdAt, ...metadata}` | `agentkit_memory` (`text`, `userId`) |
+| Chat | `agentkit:chat:<user>:<session>` → JSON `{userId, sessionId, userMessages, modelMessages, messages, createdAt, updatedAt}` | `agentkit_chat` |
+
+User and session ids are used as they are, so the same id reads the same keys from Hermes and the
+TS SDK. Like the TS SDK, the provider refuses a user id with `:` (the key separator), and keeps no
+transcript for a session id with one. Indexes are created on first use. `AgentMemory` and `ChatHistory` are importable on their own for
+use outside Hermes.
+
+## Development
+
+```bash
+uv sync --all-packages && pnpm py:lint && pnpm py:test   # Redis tests need UPSTASH_REDIS_REST_* set
+uv run python python/hermes-memory/e2e/hermes_e2e.py     # a real Hermes session, needs OPENAI_API_KEY
+```
+
+The e2e script installs the package into a temporary directory and runs Hermes with a temporary
+`HERMES_HOME`, so your own Hermes install is not touched. Hermes's built-in memory is turned off
+there. One session saves two facts; a fresh session started right after must name them without
+calling any tool (checked in Hermes's `state.db`), so they can only come from the automatic recall;
+and a control session as another user must not know them. The script then checks the keys and
+transcripts in Redis (and, if `packages/sdk` is built, that the TS `AgentMemory` recalls them too)
+before cleaning up.

upstash_hermes_memory-0.1.0/e2e/hermes_e2e.py

@@ -0,0 +1,296 @@
+"""End-to-end check of the provider inside a real Hermes Agent, against a real Upstash Redis.
+
+    uv run python python/hermes-memory/e2e/hermes_e2e.py [--keep] [--model gpt-5-mini]
+
+What it does:
+1. Builds the wheel and installs it (plus upstash-redis) into a temporary directory that is put on
+   Hermes's PYTHONPATH. Hermes's own install and ~/.hermes are not touched: Hermes runs with a
+   temporary HERMES_HOME whose config.yaml selects `memory.provider: upstash`.
+2. Session 1 asks the agent to remember two facts. Session 2, a fresh session started right away,
+   asks for them back. Hermes's built-in memory is off, and session 2 must answer without calling
+   a tool (read from Hermes's state.db), so the facts can only come from the provider's automatic
+   recall. A control session as another user must not know them.
+3. Checks Redis: the memories and both transcripts landed under a unique prefix, in the documents
+   and indexes the TS SDK uses. If packages/sdk is built, the TS AgentMemory recalls the same
+   memory too.
+4. Drops the e2e indexes and deletes the keys (unless --keep).
+
+Needs: Hermes installed (`hermes` on PATH), UPSTASH_REDIS_REST_URL / UPSTASH_REDIS_REST_TOKEN and
+OPENAI_API_KEY in the environment or the repo's .env.
+"""
+
+import argparse
+import json
+import os
+import shutil
+import sqlite3
+import subprocess
+import sys
+import tempfile
+import time
+import uuid
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parents[3]
+PACKAGE = REPO / "python" / "hermes-memory"
+USER_ID = "e2e-user"
+FACT_PROMPT = (
+    "Please remember this for future conversations: my cat is called Pamuk and my favourite "
+    "programming language is Elixir. Save it to your long-term memory."
+)
+RECALL_PROMPT = (
+    "What is my cat called, and what is my favourite programming language? "
+    "Answer from what you remember about me, in one sentence."
+)
+
+
+def load_dotenv(path: Path) -> None:
+    if not path.exists():
+        return
+    for line in path.read_text().splitlines():
+        if "=" in line and not line.lstrip().startswith("#"):
+            key, value = line.split("=", 1)
+            os.environ.setdefault(key.strip(), value.strip().strip('"'))
+
+
+def hermes_python() -> list[str]:
+    """Hermes's own interpreter and entry script. Its launcher unsets PYTHONPATH, so skip it."""
+    launcher = shutil.which("hermes")
+    if not launcher:
+        sys.exit("hermes is not on PATH: install Hermes Agent first")
+    home = Path(os.environ.get("HERMES_INSTALL_DIR", Path.home() / ".hermes" / "hermes-agent"))
+    python, script = home / "venv" / "bin" / "python", home / "hermes"
+    if not (python.exists() and script.exists()):
+        sys.exit(f"cannot find Hermes's venv under {home} (set HERMES_INSTALL_DIR)")
+    return [str(python), str(script)]
+
+
+def step(title: str) -> None:
+    print(f"\n== {title} ==", flush=True)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--model", default="gpt-5-mini")
+    parser.add_argument("--keep", action="store_true", help="leave the keys and indexes in Redis")
+    args = parser.parse_args()
+
+    load_dotenv(REPO / ".env")
+    for name in ("UPSTASH_REDIS_REST_URL", "UPSTASH_REDIS_REST_TOKEN", "OPENAI_API_KEY"):
+        if not os.environ.get(name):
+            sys.exit(f"{name} is not set")
+
+    from upstash_hermes_memory import AgentMemory, ChatHistory
+    from upstash_redis import Redis
+
+    run = uuid.uuid4().hex[:8]
+    memory_prefix, chat_prefix = f"e2e:hermes:{run}:memory", f"e2e:hermes:{run}:chat"
+    redis = Redis.from_env()
+    memory = AgentMemory(redis, prefix=memory_prefix, enable_telemetry=False)
+    chats = ChatHistory(redis, prefix=chat_prefix, enable_telemetry=False)
+    work = Path(tempfile.mkdtemp(prefix="hermes-e2e-"))
+    failures: list[str] = []
+
+    def check(ok: bool, what: str) -> None:
+        print(f"  {'ok  ' if ok else 'FAIL'} {what}")
+        if not ok:
+            failures.append(what)
+
+    try:
+        step("install the provider next to Hermes (temporary)")
+        dist, site, home = work / "dist", work / "site", work / "home"
+        subprocess.run(
+            ["uv", "build", "--wheel", "--package", "upstash-hermes-memory", "--out-dir", dist],
+            cwd=REPO,
+            check=True,
+            capture_output=True,
+        )
+        (wheel,) = dist.glob("*.whl")
+        # --no-deps: httpx and friends come from Hermes's venv, only upstash-redis is missing there.
+        subprocess.run(
+            [
+                "uv",
+                "pip",
+                "install",
+                "--quiet",
+                "--no-deps",
+                "--target",
+                site,
+                wheel,
+                "upstash-redis==1.8.0",
+            ],
+            check=True,
+        )
+        home.mkdir()
+        # Hermes's own stores (MEMORY.md / USER.md) default to on. Off, they cannot carry the
+        # facts from session 1 to session 2: the provider is the only way across.
+        (home / "config.yaml").write_text(
+            f"model:\n  provider: openai-api\n  default: {args.model}\n"
+            "memory:\n  provider: upstash\n  memory_enabled: false\n  user_profile_enabled: false\n"
+        )
+        env = {
+            **os.environ,
+            "HERMES_HOME": str(home),
+            "PYTHONPATH": str(site),
+            "UPSTASH_HERMES_MEMORY_PREFIX": memory_prefix,
+            "UPSTASH_HERMES_CHAT_PREFIX": chat_prefix,
+        }
+        print(f"  HERMES_HOME={home}\n  prefixes {memory_prefix} / {chat_prefix}")
+
+        def hermes(
+            prompt: str, user: str = USER_ID, hermes_home: Path = home
+        ) -> tuple[str, list[str]]:
+            """Run one fresh one-shot session; return its answer and the tools it called."""
+            cmd = [*hermes_python(), "-z", prompt, "--provider", "openai-api", "-m", args.model]
+            done = subprocess.run(
+                cmd,
+                check=False,
+                env={**env, "HERMES_HOME": str(hermes_home), "UPSTASH_HERMES_USER_ID": user},
+                capture_output=True,
+                text=True,
+                timeout=300,
+            )
+            if done.returncode != 0:
+                print(done.stdout, done.stderr, sep="\n")
+                raise SystemExit(f"hermes exited with {done.returncode}")
+            # Hermes records every session in $HERMES_HOME/state.db, tool results included.
+            with sqlite3.connect(hermes_home / "state.db") as db:
+                (session,) = db.execute(
+                    "SELECT session_id FROM messages WHERE role = 'user' AND content = ?"
+                    " ORDER BY id DESC LIMIT 1",
+                    (prompt,),
+                ).fetchone()
+                tools = [
+                    row[0]
+                    for row in db.execute(
+                        "SELECT tool_name FROM messages WHERE session_id = ? AND role = 'tool'"
+                        " ORDER BY id",
+                        (session,),
+                    )
+                ]
+            answer = done.stdout.strip()
+            print("  < " + answer.replace("\n", "\n    "))
+            print(f"  tools called: {tools or 'none'}")
+            return answer, tools
+
+        # The sessions run back to back, with no waiting in between: a fact the agent saved must
+        # be recallable as soon as the save tool returns.
+        step("session 1: tell the agent two facts")
+        print("  > " + FACT_PROMPT)
+        _, tools_1 = hermes(FACT_PROMPT)
+        check(
+            tools_1.count("upstash_memory_save") >= 1, "session 1 saved through upstash_memory_save"
+        )
+        check("memory" not in tools_1, "session 1 did not use Hermes's built-in memory tool")
+
+        step("session 2: a fresh session asks for them back")
+        print("  > " + RECALL_PROMPT)
+        answer, tools_2 = hermes(RECALL_PROMPT)
+        check("Pamuk" in answer, "the answer names the cat (Pamuk)")
+        check("Elixir" in answer, "the answer names the language (Elixir)")
+        # With no tool calls, the facts can only have come from the automatic recall (prefetch).
+        check(tools_2 == [], "session 2 called no tools: the facts came from automatic recall")
+
+        step("control: the same question as a user with no memories")
+        print("  > " + RECALL_PROMPT)
+        # Its own HERMES_HOME: Hermes's built-in session_search reads the sessions in state.db,
+        # whoever they belonged to, so a shared home would let it find sessions 1 and 2. This
+        # checks the Redis side only, which is what the provider controls.
+        control_home = work / "control-home"
+        control_home.mkdir()
+        shutil.copy(home / "config.yaml", control_home / "config.yaml")
+        control, _ = hermes(RECALL_PROMPT, user=f"{USER_ID}-control", hermes_home=control_home)
+        check("Pamuk" not in control, "another user's session does not know the cat's name")
+
+        step("Hermes's built-in stores stayed empty")
+        builtin = [
+            p for p in (home / "memories").glob("*") if p.is_file() and p.read_text().strip()
+        ]
+        print(f"  {home / 'memories'}: {[p.name for p in builtin] or 'empty'}")
+        check(not builtin, "MEMORY.md / USER.md hold nothing")
+
+        step("Redis: memories")
+        memory.index.wait_indexing()
+        saved = memory.list(user_id=USER_ID)
+        for record in saved:
+            print(
+                f"  memory {memory_prefix}:{USER_ID}:{record.id} -> {record.text!r} {record.metadata}"
+            )
+        text = " ".join(r.text for r in saved)
+        check("Pamuk" in text, "a memory mentioning Pamuk was saved")
+        check("Elixir" in text, "a memory mentioning Elixir was saved")
+
+        step("Redis: chat history")
+        chats.index.wait_indexing()
+        sessions = chats.list_chats(user_id=USER_ID)
+        for doc in sessions:
+            roles = [m["role"] for m in doc["messages"]]
+            print(f"  chat {chat_prefix}:{USER_ID}:{doc['sessionId']} messages={roles}")
+        check(len(sessions) == 2, "both sessions were saved as transcripts")
+        check(
+            any("Pamuk" in d.get("userMessages", "") for d in sessions),
+            "session 1's transcript holds the user's message",
+        )
+        hits = chats.search_chats("cat Pamuk", user_id=USER_ID)
+        check(bool(hits), "the transcripts are searchable (search_chats 'cat Pamuk')")
+
+        step("Redis: layout shared with the TS SDK")
+        key = f"{memory_prefix}:{USER_ID}:{saved[0].id}" if saved else ""
+        doc = redis.execute(["JSON.GET", key]) if key else None
+        print(f"  JSON.GET {key} -> {json.dumps(doc)}")
+        check(
+            isinstance(doc, dict) and {"text", "userId", "createdAt"} <= set(doc),
+            "memory documents have the AgentMemory shape",
+        )
+        ts_dist = REPO / "packages" / "sdk" / "dist" / "index.js"
+        if ts_dist.exists() and shutil.which("node"):
+            script = (
+                "const { AgentMemory } = await import(process.argv[1]);"
+                "const { Redis } = await import('@upstash/redis');"
+                "const m = new AgentMemory({ redis: Redis.fromEnv(), prefix: process.argv[2],"
+                " enableTelemetry: false });"
+                "const hits = await m.recall({ query: 'cat Pamuk', userId: process.argv[3] });"
+                "console.log(JSON.stringify(hits.map((h) => h.text)));"
+            )
+            out = subprocess.run(
+                ["node", "--input-type=module", "-e", script, str(ts_dist), memory_prefix, USER_ID],
+                check=False,
+                cwd=REPO / "packages" / "sdk",
+                capture_output=True,
+                text=True,
+            )
+            print(f"  TS AgentMemory.recall -> {out.stdout.strip() or out.stderr.strip()[:300]}")
+            check("Pamuk" in out.stdout, "the TS SDK recalls the memory Hermes saved")
+        else:
+            print("  (skipped: build packages/sdk to cross-check with the TS SDK)")
+    finally:
+        if args.keep:
+            print(
+                f"\n--keep: left {memory_prefix}* and {chat_prefix}* in Redis, HERMES_HOME {work}"
+            )
+        else:
+            for index in (memory.index, chats.index):
+                try:
+                    index.drop()
+                except Exception as error:  # noqa: BLE001 - cleanup is best effort
+                    print(f"  could not drop {index.name}: {error}")
+            for prefix in (memory_prefix, chat_prefix):
+                cursor = 0
+                while True:
+                    cursor, keys = redis.scan(cursor, match=f"{prefix}*", count=200)
+                    if keys:
+                        redis.delete(*keys)
+                    if int(cursor) == 0:
+                        break
+            shutil.rmtree(work, ignore_errors=True)
+
+    print(f"\n{'E2E PASSED' if not failures else 'E2E FAILED: ' + '; '.join(failures)}")
+    sys.exit(1 if failures else 0)
+
+
+if __name__ == "__main__":
+    start = time.monotonic()
+    try:
+        main()
+    finally:
+        print(f"({time.monotonic() - start:.0f}s)")

upstash_hermes_memory-0.1.0/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "upstash-hermes-memory",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Version carrier for the upstash-hermes-memory PyPI package. Changesets bumps it; scripts/sync-version.mjs copies it into pyproject.toml."
+}

upstash_hermes_memory-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "upstash-hermes-memory"
+version = "0.1.0"
+description = "Upstash Redis memory provider for Hermes Agent: long-term memory, searchable chat history and recall on Redis Search, with no separate vector database."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+dependencies = ["upstash-redis>=1.8.0"]
+
+# Hermes discovers pip-installed memory providers through this group; the entry-point name is the
+# value of `memory.provider` in Hermes's config.yaml.
+[project.entry-points."hermes_agent.memory_providers"]
+upstash = "upstash_hermes_memory:register"
+
+[project.urls]
+Homepage = "https://github.com/upstash/agentkit"
+Repository = "https://github.com/upstash/agentkit"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

upstash_hermes_memory-0.1.0/src/upstash_hermes_memory/__init__.py

@@ -0,0 +1,27 @@
+"""Upstash Redis memory provider for Hermes Agent.
+
+Hermes stopped taking new memory providers in its own repository: they ship as standalone plugins
+and are listed in its plugin catalog. This package is that plugin, and it lives in the AgentKit
+monorepo rather than in a repository of its own so the Python port reads and writes exactly the
+keys and Redis Search indexes the TypeScript SDK does. A memory saved from an AI SDK app is then
+recalled by a Hermes agent on the same database.
+"""
+
+from ._version import VERSION
+from .chat_history import ChatHistory
+from .memory import AgentMemory, MemoryRecord
+from .provider import UpstashMemoryProvider
+
+__all__ = [
+    "VERSION",
+    "AgentMemory",
+    "ChatHistory",
+    "MemoryRecord",
+    "UpstashMemoryProvider",
+    "register",
+]
+
+
+def register(ctx) -> None:
+    """Hermes plugin entry point (`hermes_agent.memory_providers`)."""
+    ctx.register_memory_provider(UpstashMemoryProvider())

upstash_hermes_memory-0.1.0/src/upstash_hermes_memory/_search.py

@@ -0,0 +1,91 @@
+"""A Redis Search index that is created on first use, shared by AgentMemory and ChatHistory.
+
+The commands are the ones `ReactiveSearchIndex` sends from the TS SDK, argument for argument, so
+an index created from either language is the same index.
+"""
+
+import json
+import threading
+from collections.abc import Sequence
+from typing import Any
+
+# (field, type, no_tokenize)
+Field = tuple[str, str, bool]
+
+
+def index_name_for(prefix: str) -> str:
+    """The TS default: every character outside [a-zA-Z0-9_] becomes `_`."""
+    return "".join(c if c.isascii() and (c.isalnum() or c == "_") else "_" for c in prefix)
+
+
+def dumps(value: Any) -> str:
+    """JSON the way JSON.stringify writes it, so stored documents match the TS SDK's."""
+    return json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+
+
+class SearchIndex:
+    def __init__(self, redis: Any, *, name: str, prefix: str, schema: Sequence[Field]):
+        self.redis = redis
+        self.name = name
+        self.prefix = prefix
+        self.schema = list(schema)
+        self._ready = False
+        self._lock = threading.Lock()
+
+    def create_command(self) -> list[str]:
+        cmd = ["SEARCH.CREATE", self.name, "EXISTSOK", "ON", "JSON", "PREFIX", "1", self.prefix]
+        cmd.append("SCHEMA")
+        for field, type_, no_tokenize in self.schema:
+            cmd += [field, type_] + (["NOTOKENIZE"] if no_tokenize else [])
+        return cmd
+
+    def ensure(self) -> None:
+        """Create the index if it does not exist yet. A no-op after the first call."""
+        if self._ready:
+            return
+        with self._lock:
+            if self._ready:
+                return
+            self.redis.execute(self.create_command())
+            self.redis.execute(["SEARCH.WAITINDEXING", self.name])
+            self._ready = True
+
+    def query(self, filter: dict[str, Any], limit: int | None = None) -> list[Any]:
+        self.ensure()
+        rows = self._query(filter, limit)
+        if not rows and self._raw_count(filter) < 0:
+            # The Python client turns a missing index into [], so an empty result is ambiguous.
+            # COUNT says -1 when the index is gone (another client dropped it): recreate, retry once.
+            self._ready = False
+            self.ensure()
+            rows = self._query(filter, limit)
+        return rows
+
+    def count(self, filter: dict[str, Any]) -> int:
+        self.ensure()
+        count = self._raw_count(filter)
+        if count < 0:
+            # -1 means the index is gone (dropped after we created it): recreate it and retry once.
+            self._ready = False
+            self.ensure()
+            count = self._raw_count(filter)
+        return max(count, 0)
+
+    def _query(self, filter: dict[str, Any], limit: int | None) -> list[Any]:
+        cmd = ["SEARCH.QUERY", self.name, dumps(filter)]
+        if limit is not None:
+            cmd += ["LIMIT", str(limit)]
+        return list(self.redis.execute(cmd) or [])
+
+    def _raw_count(self, filter: dict[str, Any]) -> int:
+        result = self.redis.execute(["SEARCH.COUNT", self.name, dumps(filter)])
+        return int(getattr(result, "count", result))
+
+    def wait_indexing(self) -> None:
+        """Block until every write so far is searchable (and every delete has left the index)."""
+        self.ensure()
+        self.redis.execute(["SEARCH.WAITINDEXING", self.name])
+
+    def drop(self) -> None:
+        self.redis.execute(["SEARCH.DROP", self.name])
+        self._ready = False

upstash_hermes_memory-0.1.0/src/upstash_hermes_memory/_telemetry.py

@@ -0,0 +1,27 @@
+"""Tags the redis client's telemetry header, the Python counterpart of the TS SDK's addTelemetry."""
+
+import os
+from typing import Any
+
+from ._version import VERSION
+
+SDK_TELEMETRY = f"upstash-hermes-memory@{VERSION}"
+
+_HEADER = "Upstash-Telemetry-Sdk"
+
+
+def add_telemetry(redis: Any, *, enabled: bool = True) -> None:
+    """Append this package's tag to the `Upstash-Telemetry-Sdk` header, once per client.
+
+    upstash-redis only sends the header when the client allows telemetry, so a client created
+    with `allow_telemetry=False` stays untagged, as does any process with
+    `UPSTASH_DISABLE_TELEMETRY` set.
+    """
+    if not enabled or os.environ.get("UPSTASH_DISABLE_TELEMETRY"):
+        return
+    headers = getattr(redis, "_headers", None)
+    if not isinstance(headers, dict) or _HEADER not in headers:
+        return
+    tags = headers[_HEADER].split(",")
+    if SDK_TELEMETRY not in tags:
+        headers[_HEADER] = ",".join([*tags, SDK_TELEMETRY])

upstash_hermes_memory-0.1.0/src/upstash_hermes_memory/_version.py

@@ -0,0 +1,2 @@
+# Generated by scripts/sync-version.mjs (run by `pnpm ci:version`) — do not edit by hand.
+VERSION = "0.1.0"