fix(hindsight): complete recall tool methods

[akhater]

Summary

Updates hindsight_recall so agents can choose the retrieval strategy and filters per call while keeping the default call backward compatible.

The core implementation was rebuilt from Thomas Marcelis's cleaner branch, ThomasMarcelis/hermes-agent:jd/hindsight-recall-methods-clean, and preserved as a Thomas-authored commit. A small follow-up commit only adds Thomas to AUTHOR_MAP and marks an existing docs table for ascii-guard so CI can pass.

Changes

• Adds optional hindsight_recall controls: method, budget, max_tokens, types, tags, tags_match, tag_groups, metadata, max_entity_tokens, limit, and offset.
• Keeps method="recall" as the default semantic recall path using client.arecall(...).
• Implements method="list" through the public client.memory.list_memories(...) API with pagination and formatted output.
• Implements method="entity" through client.arecall(..., include_entities=True) and formats memory plus entity context.
• Supports configured recall tags/types as defaults and allows per-call overrides.
• Applies exact-match metadata post-filtering to returned memories and entity output.
• Adds documentation for the expanded tool behavior.
• Adds regression tests for schema exposure, per-call controls, invalid fallback behavior, list formatting/filtering, metadata filtering, and entity formatting.

Validation

• python3 -m py_compile scripts/release.py plugins/memory/hindsight/__init__.py tests/plugins/memory/test_hindsight_provider.py
• uv run --extra dev pytest tests/plugins/memory/test_hindsight_provider.py -q -o addopts=: 107 passed
• uv run --extra dev pytest tests/plugins/memory -q -o addopts=: 153 passed
• uv run --extra dev ruff check plugins/memory/hindsight/__init__.py tests/plugins/memory/test_hindsight_provider.py
• git diff --check origin/main...HEAD

Note: local npm run lint:diagrams could not be run because ascii-guard was not installed in this temporary worktree; the added ignore markers match existing repo convention and CI will validate it.

[poruru-code]

@akhater
Thanks for working on this.

Now that the retain-side tagging/metadata work from #6290 landed via #13987, would you be open to extending this a bit to support recall filtered by tags and/or metadata as well?

That seems like the natural next step here.

[ThomasMarcelis]

Clean fix prepared, but I could not push directly to this PR head branch from the available GitHub token.

Why: PR #8281 is from akhater/hermes-agent:feat/hindsight-recall-params. GitHub reports this authenticated account has push: false on that fork, and API commit-on-branch is forbidden, so the existing PR branch cannot be updated from here.

Clean replacement branch/commit is available here:

• Branch: ThomasMarcelis/hermes-agent:jd/hindsight-recall-methods-clean
• Commit: ThomasMarcelis@65c71f8

Summary of the fix:

• Rebased on current origin/main; no dirty/conflicting merge state in the clean branch.
• Adds complete hindsight_recall schema controls for method, per-call budget, max_tokens, types, tags/tag matching/tag groups, metadata post-filtering, list pagination, and entity token limits.
• Implements method="list" via public client.memory.list_memories(...), using configured timeout and clean formatting.
• Implements method="entity" against current hindsight-client models where RecallResponse.entities is a dict of EntityStateResponse objects with canonical_name and observations.
• Adds regression tests for schema exposure, per-call controls, invalid fallback behavior, list formatting/filtering, metadata filtering, and entity formatting.

Validation run locally:

• py_compile on changed files: passed
• pytest tests/plugins/memory/test_hindsight_provider.py -q -o 'addopts=': 100 passed
• pytest tests/plugins/memory -q -o 'addopts=': 146 passed
• ruff check plugins/memory/hindsight/__init__.py tests/plugins/memory/test_hindsight_provider.py: passed
• git diff --check: passed
• conflict-marker scan: clean

To make this PR merge-ready, the PR author or someone with push access to akhater/hermes-agent:feat/hindsight-recall-params should replace/update the branch with the clean commit above.

[akhater]

Updated this PR branch with the cleaner implementation from Thomas Marcelis's replacement branch.

What changed:

• Rebuilt on current origin/main.
• Preserved Thomas as the commit author in a single clean commit: 153af57d8.
• Switched method="list" to the public client.memory.list_memories(...) API.
• Added tag/type/metadata/list/entity controls, docs, and regression tests.

Validation I ran after the branch update:

• python3 -m py_compile plugins/memory/hindsight/__init__.py tests/plugins/memory/test_hindsight_provider.py
• uv run --extra dev pytest tests/plugins/memory/test_hindsight_provider.py -q -o addopts=: 107 passed
• uv run --extra dev pytest tests/plugins/memory -q -o addopts=: 153 passed
• uv run --extra dev ruff check plugins/memory/hindsight/__init__.py tests/plugins/memory/test_hindsight_provider.py
• git diff --check origin/main...HEAD

Credit to Thomas for the cleaner implementation and test coverage.

[akhater]

Follow-up pushed: fc3ab52b9.

This is only CI housekeeping on top of Thomas's implementation commit:

• Added thomasmarcelis@gmail.com -> ThomasMarcelis to scripts/release.py AUTHOR_MAP.
• Added existing ascii-guard ignore markers around a pre-existing Markdown table in skills.md that was blocking the docs workflow.

Re-ran:

• python3 -m py_compile scripts/release.py plugins/memory/hindsight/__init__.py tests/plugins/memory/test_hindsight_provider.py
• uv run --extra dev pytest tests/plugins/memory -q -o addopts=: 153 passed
• git diff --check origin/main...HEAD

[teknium1]

Thanks for the expanded recall implementation and focused Hindsight coverage. The current main premise is valid: plugins/memory/hindsight/__init__.py:314-325 exposes only query, and the handler at :1729-1751 only forwards configured controls.

Problems

• PR head plugins/memory/hindsight/__init__.py:1461 resets an absent recall_types configuration to None. Current main deliberately defaults to ['observation'] at :699-707 and :1344-1351 (490b3e76b), so this needs reconciliation rather than a direct salvage.
• The branch also carries unrelated model metadata, gateway reply, and global fixture changes (713020d8, 35cc8ac0, 44923486). The intended commit a60a1616 is limited to Hindsight files.

Suggested changes

• Preserve main's observation-only default and add coverage for it alongside the new per-call override behavior.
• Define/test whether entity retrieval should override that default with world; as written, its default_types fallback is bypassed once main's default is retained.
• Salvage only the Hindsight-focused changes and keep unrelated fixes separate.

This is an automated hermes-sweeper review.

[teknium1]

Current main deliberately defaults absent recall_types to ['observation'] (490b3e76b; current main lines 1344-1351). _normalize_recall_types(None) returns None, so carrying this line forward would silently widen default recall. Preserve the main default and add a regression test for an absent config value.

[teknium1]

This model-context-resolution change is unrelated to the stated Hindsight recall work. Please exclude it from the Hindsight salvage so its behavior can be reviewed independently.

[alt-glitch]

This was generated by AI during triage.

Related to open #18268. This branch describes a rebuild of that recall-method work but also contains additional live surfaces, so it is treated as salvage/competing work rather than a duplicate; please isolate the intended contribution.

[alt-glitch]

This was generated by AI during triage.

Related to #18268 for the Hindsight recall-method work. This live branch also changes unrelated model metadata, Telegram delivery, and MCP tool-name handling, so it is not a duplicate; please consider splitting those scopes for review.

[alt-glitch]

This was generated by AI during triage.

Related to open #18268, which covers the same Hindsight recall-method goal. This branch also changes model metadata, Telegram reply routing, and MCP naming, so it is retained as competing mixed-scope work rather than marked duplicate; please split or rebase for review.

[alt-glitch]

This was generated by AI during triage.

Related to focused open #18268 for the Hindsight recall-method feature. This live patch also changes model metadata and Telegram routing; please split or rebase those independent hunks for review.