Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
fix comments
  • Loading branch information
Alanxtl committed Aug 20, 2026
commit d8a45ca6074235003a01f16fb3134845d217019f
15 changes: 10 additions & 5 deletions integrations/hermes/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,15 +27,20 @@ powercontext server run

## Configuration

The provider uses `http://127.0.0.1:8000` by default. Run the Hermes memory setup
wizard to configure and activate it interactively; the wizard writes
non-sensitive values to `$HERMES_HOME/powercontext/config.json`, stores the
authorization header in Hermes' `.env` file, and sets `memory.provider`:
The provider uses `http://127.0.0.1:8000` by default. Run the generic Hermes
memory setup wizard and select `PowerContext` to configure and activate it
interactively; the wizard writes non-sensitive values to
`$HERMES_HOME/powercontext/config.json`, stores the authorization header in
Hermes' `.env` file, and sets `memory.provider`:

```bash
hermes memory setup powercontext
hermes memory setup
```

On Hermes v0.20.4, use the generic command above instead of
`hermes memory setup powercontext`; the provider-specific shortcut does not
open the configuration wizard.

Configuration can also be stored manually in `$HERMES_HOME/powercontext/config.json`:

```json
Expand Down
8 changes: 6 additions & 2 deletions integrations/hermes/plugins/powercontext/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,12 +10,16 @@ The plugin deliberately uses only the Python standard library for HTTP, so it
can be copied into Hermes without adding an HTTP client dependency. Its
provider configuration is read from `$HERMES_HOME/powercontext/config.json`.

The provider participates in Hermes' generic memory setup wizard:
The provider participates in Hermes' generic memory setup wizard. Run the
command below and select `PowerContext` from the provider list:

```bash
hermes memory setup powercontext
hermes memory setup
```

On Hermes v0.20.4, `hermes memory setup powercontext` only selects the provider
and does not open the provider configuration wizard.

Non-sensitive values are saved to `powercontext/config.json`; authorization is saved
through Hermes' `.env` secret store.

Expand Down
72 changes: 51 additions & 21 deletions integrations/hermes/plugins/powercontext/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -814,12 +814,7 @@ def _remember_new(self, target: str, text: str) -> None:
self._memory_map[key] = identity
self._save_memory_map()

def _find_memory_citation(
self,
text: str,
*,
identity: dict[str, str] | None = None,
) -> dict[str, Any] | None:
def _find_memory_citations(self, text: str) -> list[dict[str, Any]]:
try:
response = self._client.search_memory(
self._scope_id,
Expand All @@ -829,30 +824,65 @@ def _find_memory_citation(
)
except PowerContextError:
logger.debug("PowerContext memory citation lookup failed", exc_info=True)
return None
return []
hits = response.get("hits", []) if isinstance(response, dict) else []
citations: list[dict[str, Any]] = []
identities: set[tuple[str, str]] = set()
for hit in hits:
if not isinstance(hit, dict) or str(hit.get("text", "")).strip() != text.strip():
if not isinstance(hit, dict):
continue
hit_text = str(hit.get("text", "")).strip()
if not hit_text or text.strip() not in hit_text:
continue
citation = hit.get("citation")
normalized = _citation_from_response({"entry": {"citation": citation}})
if normalized is not None and (identity is None or _entry_identity(normalized) == identity):
return normalized
entry_identity = _entry_identity(normalized)
if entry_identity is None:
continue
identity_key = (entry_identity["entry_id"], entry_identity["entry_version_id"])
if identity_key in identities:
continue
identities.add(identity_key)
citations.append(normalized)
return citations

def _find_memory_citation(
self,
text: str,
*,
identity: dict[str, str] | None = None,
) -> dict[str, Any] | None:
for citation in self._find_memory_citations(text):
if identity is None or _entry_identity(citation) == identity:
return citation
return None

def _lookup_memory_citation(self, target: str, text: str) -> tuple[str, dict[str, Any] | None]:
key = self._memory_item_key(target, text)
stored = self._memory_map.get(key)
identity = _entry_identity(stored)
citation = self._find_memory_citation(text, identity=identity)
if citation is None and identity is None:
citation = self._find_memory_citation(text)
if citation is not None:
stable_identity = _entry_identity(citation)
if stable_identity is not None and self._memory_map.get(key) != stable_identity:
self._memory_map[key] = stable_identity
self._save_memory_map()
return key, citation
query = text.strip()
if not query:
return key, None

candidates = self._find_memory_citations(query)
target_prefix = f"{self._scope_id}:{target}:"
matches: list[tuple[str, dict[str, Any]]] = []
for mapped_key, stored in self._memory_map.items():
if not mapped_key.startswith(target_prefix):
continue
identity = _entry_identity(stored)
if identity is None:
continue
matching_candidates = [candidate for candidate in candidates if _entry_identity(candidate) == identity]
if len(matching_candidates) == 1:
matches.append((mapped_key, matching_candidates[0]))

if len(matches) != 1:
logger.debug(
"Skipping Hermes memory change because old_text matched %d mapped entries",
len(matches),
)
return key, None
return matches[0]

def _apply_memory_change(self, action: str, target: str, content: str, old_text: str) -> None:
old_key, citation = self._lookup_memory_citation(target, old_text)
Expand Down
45 changes: 45 additions & 0 deletions tests/integrations/test_hermes_provider.py
Original file line number Diff line number Diff line change
Expand Up @@ -413,6 +413,51 @@ def test_memory_write_retires_mapped_entries_for_replace_and_remove(provider_and
assert provider._memory_map == {}


def test_memory_write_matches_partial_old_text_for_replace_and_remove(provider_and_client):
provider, client = provider_and_client

provider.on_memory_write("add", "user", "The user prefers uv.")
provider._wait_for_background()
provider.on_memory_write(
"replace",
"user",
"The user prefers rye.",
{"old_text": "prefers uv"},
)
provider._wait_for_background()
provider.on_memory_write(
"remove",
"user",
"",
{"old_text": "prefers rye"},
)
provider._wait_for_background()

retire_calls = [call for call in client.calls if call[0] == "retire_memory_entry"]
assert [call[1][1]["entry_id"] for call in retire_calls] == ["entry-1", "entry-2"]
assert [call[1][1]["memory_ref"]["revision"] for call in retire_calls] == [1, 3]
assert provider._memory_map == {}


def test_memory_write_does_not_retire_unmapped_same_text(provider_and_client):
provider, client = provider_and_client
text = "The user prefers uv."
client.remember_memory(
provider._scope_id,
kind="preference",
text=text,
reason="created directly in PowerContext",
)
client.calls.clear()

provider.on_memory_write("remove", "user", "", {"old_text": text})
provider._wait_for_background()

assert [call[0] for call in client.calls] == ["search_memory"]
assert text in client._memory_entries
assert provider._memory_map == {}


def test_memory_map_refreshes_revision_after_multiple_writes(provider_and_client):
provider, client = provider_and_client

Expand Down