penfieldlabs/hermes-penfield

Name: hermes-penfield
Author: penfieldlabs

🧠 Penfield memory provider for Hermes agent

★ 1 langPython licenseMIT updated2026-07-01

overview

hermes-penfield is a persistent memory provider that enables Hermes Agent to maintain memory across different sessions and agents. It connects the agent to the Penfield memory API using a stdlib-only HTTP implementation with OAuth and API-key authentication. The provider utilizes hybrid search and a knowledge graph with 24 relationship types to manage memories and artifacts. It also automatically saves checkpoints of relevant memories when context compression occurs.

17 tools for memory management and knowledge graph traversal
Hybrid search combining BM25, vector, and graph methods
Automatic context checkpointing during message compression

full readme from github

hermes-penfield

Penfield persistent memory provider for Hermes Agent.

Connects Hermes Agent to the Penfield memory API. Exposes 17 tools mirroring the Penfield MCP surface. Stdlib-only HTTP, OAuth device-code

API-key authentication, dev/prod environment switching.

Penfield gives Hermes cross-session, cross-agent memory with hybrid search (BM25 + vector + graph), typed connections (24 relationship types), and artifact storage.

Requirements

Hermes Agent installed and runnable (hermes on your PATH).
A Penfield account and API key — create one at portal.penfield.app.

Install

hermes plugins install penfieldlabs/hermes-penfield --enable

That's it. Hermes clones the repo, drops it into ~/.hermes/plugins/penfield/, and enables it. The plugin is self-contained — no pip install needed.

Configure

Set memory.provider: penfield in ~/.hermes/config.yaml:

hermes config set memory.provider penfield

Then authenticate:

hermes penfield login

Or set an API key directly in ~/.hermes/.env:

PENFIELD_API_KEY=tm_pf_yourtenant_ak_yourkey
PENFIELD_ENV=prod

When context compression discards messages, the provider saves a Penfield checkpoint capturing the relevant memories from your knowledge graph. On by default; set pre_compress_save: false in penfield/config.json to disable.

Use

hermes

The persona and persistent context load automatically on every session. The 17 tools are available to the agent:

Tool	What it does
`penfield_awaken`	Load persona + persistent context briefing
`penfield_store`	Store a memory (auto-detected type)
`penfield_recall`	Hybrid search (BM25 + vector + graph)
`penfield_search`	Semantic search for fuzzy concept matching
`penfield_fetch`	Get a memory by ID
`penfield_update_memory`	Update a memory
`penfield_connect`	Create a relationship between memories
`penfield_disconnect`	Remove a relationship between memories
`penfield_explore`	Traverse the knowledge graph from a memory
`penfield_reflect`	Analyze memory patterns over a time window
`penfield_save_artifact`	Store a file (not searchable via recall)
`penfield_retrieve_artifact`	Get a stored file by path
`penfield_list_artifacts`	List files under a directory prefix
`penfield_delete_artifact`	Delete a stored file by path
`penfield_list_contexts`	List saved context checkpoints
`penfield_restore_context`	Restore a checkpoint by name
`penfield_save_context`	Create a checkpoint with reference parsing

Development

git clone https://github.com/penfieldlabs/hermes-penfield.git
cd hermes-penfield
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest -m "not integration"