deployment

Deployment

hermes-cashew supports multiple deployment methods depending on the use case.

Via hermes plugins install (Recommended for End Users)

The standard installation method clones the repository to the Hermes plugins directory:

hermes plugins install magnus919/hermes-cashew

This clones the repository to $HERMES_HOME/plugins/cashew/. The flat-entry loader in the root __init__.py bridges the directory layout to the nested plugins/memory/cashew/ implementation module.

After install, set cashew as the active memory provider and restart the gateway:

hermes config set memory.provider cashew
hermes gateway restart

Post-Install Verification

hermes memory status

Expected output shows Provider: cashew with Plugin: installed and Status: available.

Troubleshooting

If the plugin shows NOT installed, cashew-brain may not be installed in the Hermes venv:

~/.hermes/hermes-agent/venv/bin/python3 -m pip install cashew-brain

If the plugin shows Status: not available, verify dependencies are importable:

~/.hermes/hermes-agent/venv/bin/python3 -c "from core.context import ContextRetriever; print('ok')"

Via PyPI (pip install hermes-cashew)

The package is published to PyPI as hermes-cashew:

pip install hermes-cashew

This installs the wheel with the PEP 420 namespace layout (plugins/memory/cashew/). When installed via PyPI, the Hermes entry-point loader discovers the plugin via the hermes_agent.plugins entry point declared in pyproject.toml:

[project.entry-points."hermes_agent.plugins"]
cashew = "plugins.memory.cashew"

Development Install

For local development:

git clone https://github.com/magnus919/hermes-cashew
cd hermes-cashew
pip install -e ".[dev]"

When developing with a local Hermes Agent install, a symlink is also needed because Hermes inserts ~/.hermes/hermes-agent/ at the front of sys.path:

~/.hermes/hermes-agent/venv/bin/python3 -m pip install -e ".[dev]"
ln -sf "$PWD/plugins/memory/cashew" ~/.hermes/hermes-agent/plugins/memory/cashew

Release Process

Releases are triggered by pushing a v* tag to the repository:

# After PR is merged to main
git checkout main && git pull
# Update version in pyproject.toml and CHANGELOG.md
git commit -s -m "chore: bump to vX.Y.Z"
git tag vX.Y.Z && git push origin main --tags
# Create GitHub Release with notes:
gh release create vX.Y.Z --title "vX.Y.Z -- Title" --notes "..."

The release workflow (.github/workflows/release.yml):

1. Validates the tag matches pyproject.toml version
2. Runs tests
3. Syncs both plugin.yaml files to match pyproject.toml version
4. Builds wheel and sdist
5. Publishes to PyPI via OIDC trusted publishing (no API token needed)

Plugin Version Manifest

Three files must have matching versions:

File	Role	Who Bumps
pyproject.toml	PyPI package version	You (release commit)
plugin.yaml (root)	hermes plugins install manifest	CI auto-syncs
plugins/memory/cashew/plugin.yaml	Bundled-loader manifest	CI auto-syncs

The CI workflow reads the version from pyproject.toml and patches both plugin.yaml files with sed before building.

Uninstall

hermes plugins remove cashew
hermes config set memory.provider built-in
rm -rf ~/.hermes/cashew   # optional: remove the local graph data