name	hermes-cashew
description	Guide for working on the hermes-cashew plugin — a Hermes Agent memory provider backed by Cashew thought-graph memory (SQLite + local embeddings). Use when making changes to the plugin, tests, config, or CI pipeline.

hermes-cashew Development

Architecture

Thin adapter around upstream cashew-brain. The plugin delegates retrieval, schema management, and LLM operations to upstream. Custom code is limited to the Hermes integration surface.

Key Files

File	Purpose
`plugins/memory/cashew/__init__.py`	CashewMemoryProvider class + register() entry point
`plugins/memory/cashew/config.py`	CashewConfig dataclass, defaults, load/save, schema
`plugins/memory/cashew/tools.py`	JSON envelope builders for tool call responses
`plugins/memory/cashew/sleep_refactor.py`	Refactored sleep cycle (vectorized, batch-scalable)
`plugins/memory/cashew/sleep_cron_script.py`	Cron script entry point for Hermes scheduler
`plugins/memory/cashew/verify.py`	Verification helpers
`tests/`	pytest suite (236 tests)
`__init__.py` (root)	Re-export shim — delegates to plugins.memory.cashew

Layout Note

Two load paths must work:

pip install: import plugins.memory.cashew (wheel exposes plugins/)
hermes plugins install: Root __init__.py re-exports from nested module

plugins/ and plugins/memory/ are PEP 420 namespace packages (no __init__.py).

Dev Commands

pip install -e ".[dev]"    # one-command setup
pytest                      # run all tests (236)
ruff check .               # lint
mypy --explicit-package-bases plugins/memory/cashew/   # type check (strict)
vulture plugins/memory/cashew/ --min-confidence 80     # dead code
deptry .                   # unused deps
python scripts/check-duplicates.py   # duplicate detection

Key Constraints

No ~/.hermes writes. All paths scoped under hermes_home. Tests use tmp_path.
sync_turn < 10ms. Bounded queue + non-daemon worker thread.
Cashew dependency: cashew-brain>=1.1.0,<2.0.0
HF_HUB_OFFLINE=1 in tests. Embedding model must be mocked.
Silent degrade on Cashew failures — log WARNING, return empty, never raise.

Config Keys (31 keys)

Config is stored in $HERMES_HOME/cashew.json. See plugins/memory/cashew/config.py for the full CashewConfig dataclass and DEFAULTS.

Notable keys:

embedding_model: Model for vector embeddings (default: thenlper/gte-large)
llm_aux_role: Hermes config role for LLM extraction (default: None = heuristic)
sleep_schedule: Cron expression for sleep cycles (default: 0 */12 * * *)
db_path_override: Override default cashew/brain.db path

Threading Model

sync_turn(): Hot path, returns <10ms. Pushes (user, assistant, session_id) tuple onto bounded queue.Queue(maxsize=16).
Worker thread: Single non-daemon thread drains queue, calls Cashew extraction API.
Sentinel: _SHADOW = object() sent to queue on shutdown, worker exits gracefully.
shutdown(): Joins worker with 30s timeout, logs WARNING on timeout, never raises.

Testing

tmp_path fixture for all file I/O
HF_HUB_OFFLINE=1 + fake_embedder autouse fixture blocks real models
CASHEW_* env vars stripped in conftest
agent.memory_provider ABC stubbed in sys.modules

name	hermes-cashew
description	Guide for working on the hermes-cashew plugin — a Hermes Agent memory provider backed by Cashew thought-graph memory (SQLite + local embeddings). Use when making changes to the plugin, tests, config, or CI pipeline.