Skip to main content

rushdb-hermes-memory

Native RushDB persistent memory for Hermes Agent.

The provider recalls scope-authorized historical context before inference, captures completed turns without blocking the response, and uses a profile-local durable outbox so acknowledged events survive process restarts.

Requirements

  • Python 3.11–3.13
  • Hermes Agent with memory-provider entry-point support
  • A RushDB project API key from app.rushdb.com, or self-hosted RushDB and an embedding provider (see below)

Compatibility

Package RushDB 3.x and RushDB Cloud RushDB 2.x (legacy)
rushdb-hermes-memory 0.2.x (needs rushdb 3.x) 0.1.0 (rushdb 2.10.0): pip install "rushdb-hermes-memory<0.2"
rushdb (PyPI) 3.x 2.10.0: pip install "rushdb<3"

Install

Install the provider into the same Python environment as Hermes Agent:

pip install rushdb-hermes-memory
hermes memory setup

Set the RushDB project key in the Hermes environment:

export RUSHDB_API_KEY="your-project-api-key"

Optional environment variables:

  • RUSHDB_API_URL selects a different RushDB Cloud API endpoint. To self-host, run the RushDB engine and use the settings below.
  • RUSHDB_MEMORY_SCOPE_SALT makes participant hashes deployment-specific.

Self-hosted RushDB

Recall is a vector search. RushDB Cloud embeds memories for you; a self-hosted engine (rushdb) does not, so the provider embeds them itself through an OpenAI-compatible embeddings endpoint:

export RUSHDB_ENGINE_URL="http://127.0.0.1:3000"
export RUSHDB_ENGINE_TOKEN="your-engine-token"
# export RUSHDB_ENGINE_SCOPE="tenant-1"   # only for an engine started with --multitenant
export RUSHDB_EMBEDDING_API_KEY="sk-..."
export RUSHDB_EMBEDDING_MODEL="text-embedding-3-small"
export RUSHDB_EMBEDDING_DIMENSIONS="1536"
# export RUSHDB_EMBEDDING_BASE_URL="https://api.openai.com/v1"

On start the provider creates the external vector indexes it needs; every memory is written with its vector and recall searches with the embedded query. With RushDB Cloud the embedding settings are optional. When the configuration is incomplete, hermes memory status reports what is missing.

Hermes discovers the rushdb provider through the hermes_agent.memory_providers Python entry-point group.

Behavior

  • Recall searches EPISODE.summary and active MEMORY_FACT.text records with mandatory agent, profile, privacy, participant, and sandbox scope filters.
  • Recall has a short fail-open timeout and falls back to bounded recent in-process episodes.
  • Successful primary-agent turns are captured asynchronously as canonical EPISODE records.
  • Explicit Hermes memory add and replace operations are mirrored as active MEMORY_FACT records.
  • A replace (or a patch, which Hermes mirrors as a replace) deactivates the fact holding the entry it replaced and records its id in supersedesFactId; a remove deactivates the removed entry's fact. Both set validUntil and keep the old fact for history. The entry is matched by the exact previous_content Hermes reports, within the same scope and target; Hermes versions that don't report it keep the earlier fact active.
  • Writes first enter an atomic local outbox under $HERMES_HOME/rushdb-memory/outbox, then use deterministic IDs and idempotent RushDB upserts.
  • Surviving outbox files are retried while the process is running and replayed after restart.

Privacy and trust

The provider uploads bounded user and assistant text from completed primary-agent turns. It does not automatically upload Hermes' complete messages payload, system prompts, tool calls, command output, or local file paths. Subagents do not write memory.

Recalled records are formatted as untrusted historical context, never as instructions or policy. Participant identifiers are stored as hashes rather than raw platform IDs.

Development

uv sync --locked --group dev
uv run ruff format --check .
uv run ruff check .
uv run pytest
uv build

Release

CI verifies pull requests and every push to main. A successful main build publishes the version in pyproject.toml to PyPI when that exact version is not already present. Configure the pypi GitHub environment and its PYPI_TOKEN secret. Bump version before merging a subsequent release.

License

Apache-2.0

Metadata

Release files for rushdb-hermes-memory 0.2.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for rushdb-hermes-memory 0.2.2
File Size Uploaded Provenance Actions
rushdb_hermes_memory-0.2.2.tar.gz 25.8 kB With provenance Details for rushdb_hermes_memory-0.2.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for rushdb-hermes-memory 0.2.2
File Interpreter ABI Platform Actions
rushdb_hermes_memory-0.2.2-py3-none-any.whl Python 3 none any Details for rushdb_hermes_memory-0.2.2-py3-none-any.whl

Total release size: 44.9 kB

Release files / rushdb_hermes_memory-0.2.2.tar.gz

Download URL rushdb_hermes_memory-0.2.2.tar.gz
Size 25.8 kB
Tags Source
SHA-256 checksum
How to use checksums
fbe338fdc53661fc5c954b723da0fa716549043262089603a14873cb154ed79d
BLAKE2b-256 checksum
How to use checksums
b32d6f2dc462e78493e8c42bef066cf32e466c02ade294e029e547a46afb4a2d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.

Transparency log

Release files / rushdb_hermes_memory-0.2.2-py3-none-any.whl

Download URL rushdb_hermes_memory-0.2.2-py3-none-any.whl
Size 19.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
58decae2a511bc2cb3f24b8853b036f5989b02c54bbbf749c743df8d5770b614
BLAKE2b-256 checksum
How to use checksums
dfd5382647f28609ccf8e6831378be31d24aa398b54e71959dcbd99671381434
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.

Transparency log

Security for rushdb-hermes-memory 0.2.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for rushdb_hermes_memory-0.2.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page