Warning

This project is discontinued and read-only. No further development or maintenance will occur.

Hermes Hippo Memory Provider

Hippo as a real Hermes memory provider.

Install target:

• ~/.hermes/hermes-agent/plugins/memory/hippo

What it does

• activates Hippo as Hermes's external memory provider
• uses hippo context for startup context
• uses hippo recall for per-turn memory prefetch
• mirrors built-in Hermes memory writes into Hippo with hippo remember
• logs completed turns into Hippo session history with hippo session log
• applies hippo outcome --good after sessions that used recalled context
• optionally runs hippo sleep on session end

Important

• Hermes built-in memory remains active. Hippo becomes the external provider, not a total replacement for MEMORY.md and USER.md.

Install/update from local checkout

./scripts/local-install.sh

Install/update from GitHub main

curl -fsSL https://raw.githubusercontent.com/rabilrbl/hermes-hippo-memory-provider/main/scripts/remote-install.sh | bash

Activate Hippo as the Hermes memory provider

python3 - <<'PY'
from pathlib import Path
import yaml
cfg_path = Path.home() / '.hermes' / 'config.yaml'
cfg = yaml.safe_load(cfg_path.read_text()) or {}
cfg.setdefault('memory', {})['provider'] = 'hippo'
cfg_path.write_text(yaml.safe_dump(cfg, sort_keys=False))
print('set memory.provider=hippo in', cfg_path)
PY

Recommended config.yaml settings

memory:
  provider: hippo
  hippo:
    startup_budget: 250
    recall_budget: 700
    max_context_chars: 3000
    min_query_len: 12
    sync_max_chars: 2000
    status_timeout: 15
    query_timeout: 20
    write_timeout: 15
    sleep_cooldown_seconds: 900
    auto_sleep: false

Field meanings

• startup_budget: token budget for hippo context
• recall_budget: token budget for hippo recall
• max_context_chars: hard cap on Hippo text injected into Hermes
• min_query_len: skip recall for very short user messages
• sync_max_chars: max user/assistant chars stored per turn log
• status_timeout: timeout for provider availability checks
• query_timeout: timeout for hippo context and hippo recall
• write_timeout: timeout for hippo remember, hippo outcome, and hippo session log
• sleep_cooldown_seconds: minimum spacing between auto-sleep runs
• auto_sleep: whether to run hippo sleep on session end

Verify

hermes memory status
python3 -m py_compile ~/.hermes/hermes-agent/plugins/memory/hippo/__init__.py

Expected result

• hermes memory status shows Provider: hippo
• ~/.hermes/hermes-agent/plugins/memory/hippo/ contains __init__.py and plugin.yaml

Local development

uv sync --all-groups
uv run ruff check .
uv run python -m unittest discover -s tests -q
python3 -m py_compile hippo_memory_plugin/plugin.py
./scripts/build_release_zip.sh

Release artifact

• dist/hippo-memory-provider.zip
• unzip its hippo/ directory into ~/.hermes/hermes-agent/plugins/memory/

License

• MIT