feat(hermes-plugin): allow capture without automatic recall

[timeleft--]

Description

Allow a Hermes profile to keep OpenViking conversation capture and explicit memory tools while disabling automatic historical-context injection.

Before this change, keeping the provider enabled also keeps session-start and per-turn automatic recall enabled; there is no independent recall-off setting. After this change, set memory.openviking.auto_recall: false or the profile-scoped OPENVIKING_AUTO_RECALL=false override. prefetch() returns no context before recall-related client or network I/O. The default is true, preserving existing behavior without a migration.

Why this is the appropriate fix

OpenVikingMemoryProvider.prefetch() in examples/hermes-plugin/__init__.py owns both automatic context paths: the session-start memory block and per-turn query recall. Capture through sync_turn(), memory commits, and explicit tool calls use separate entrypoints. A single guard at the start of prefetch() therefore suppresses exactly the automatic behavior while leaving those capabilities available.

The guard uses the existing typed settings schema and the initialized profile's configuration/environment resolution. It does not introduce another settings parser or change profile, credential, sender, or tenant ownership. Disabling the whole provider would lose capture and tools; trimming context afterward would still incur recall I/O. A platform-specific opt-out such as #5893 cannot alone cover a profile's ordinary CLI sessions, so the two controls are complementary.

Human Involvement

• A human participated in the implementation or review loop
• This PR was generated entirely by AI agents without human participation in the loop

The human contributor selected the upstream contribution approach and reviewed the proposed behavior. Implementation and validation were AI-assisted.

Related Issue

Fixes #6084. The issue was opened before implementation; no maintainer design approval is claimed. Complements #5893's platform-specific proposal with a profile-wide control.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)
• Performance improvement
• Test update

Changes Made

• Add auto_recall through the existing boolean configuration schema and environment-resolution path.
• Gate automatic prefetch before recall client I/O while preserving capture and explicit tools.
• Document active-profile configuration and extend the existing external-provider tests.

The patch adds 67 lines across three files, including documentation and tests.

Testing

• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• I have tested this on the following platforms:
  • Linux
  • macOS
  • Windows

Validated source head: bea02a7bc6243509c33e9ad91b89bfeceb9ed728.

Test host: Hermes 7951ddd7297a284d6da48804241ee05a8a0c621c, Python 3.14.3, and the constrained plugin dependencies used by .github/workflows/hermes-plugin-tests.yml.

The issue was reproduced locally through Hermes's external-provider discovery in temporary profiles, with controlled client responses. Before the implementation, four YAML/environment × empty/nonempty-query cases failed because the disabled setting still reached recall client I/O. This is provider-level regression evidence, not a live remote-server reproduction.

Exact validation commands

Checkout paths are parameterized below as OV_ROOT (absolute OpenViking checkout path), HERMES_ROOT (absolute isolated Hermes checkout path), and VALIDATION_ROOT (absolute temporary evidence directory). The invocations and flags match the recorded validation; they do not use the user's active Hermes profile.

Dependency setup, from the pinned Hermes checkout:

cd "$HERMES_ROOT"
uv sync --frozen --group dev --no-install-project
uv export --frozen --group dev --no-emit-project --no-hashes \
  --output-file "$VALIDATION_ROOT/hermes-plugin-constraints.txt"
uv pip install --python .venv/bin/python \
  --constraint "$VALIDATION_ROOT/hermes-plugin-constraints.txt" \
  --requirement "$OV_ROOT/examples/hermes-plugin/pyproject.toml" \
  'PyYAML==6.0.3'

Focused regression and complete plugin suite, through Hermes's canonical isolated runner:

HERMES_TEST_FILE_RETRIES=0 HERMES_TEST_WORKERS=2 \
HERMES_PYTHON="$HERMES_ROOT/.venv/bin/python" scripts/run_tests.sh \
  "$OV_ROOT/examples/hermes-plugin/tests/test_standalone.py" \
  --confcutdir="$OV_ROOT/examples/hermes-plugin/tests" \
  -p no:cacheprovider -q -k auto_recall

HERMES_TEST_FILE_RETRIES=0 HERMES_TEST_WORKERS=2 \
HERMES_PYTHON="$HERMES_ROOT/.venv/bin/python" scripts/run_tests.sh \
  "$OV_ROOT/examples/hermes-plugin/tests" \
  --confcutdir="$OV_ROOT/examples/hermes-plugin/tests" \
  -p no:cacheprovider -q

Installation, activation, correctness lint, and whitespace checks, from OpenViking:

cd "$OV_ROOT"
"$HERMES_ROOT/.venv/bin/python" scripts/check-hermes-plugin-install.py \
  --hermes-root "$HERMES_ROOT" \
  --output-dir "$VALIDATION_ROOT/plugin-install-check-committed"

"$HERMES_ROOT/.venv/bin/python" -m ruff check --select E9,F63,F7,F82 \
  examples/hermes-plugin/__init__.py \
  examples/hermes-plugin/tests/test_standalone.py

git diff --check 46e15a248863831e34c4602dc96112b0b120aae2 HEAD

Results:

• Focused regression: six passed. Covers YAML/environment configuration, empty/nonempty queries, unchanged default context, explicit search results, unchanged tool schemas, and captured user/assistant messages.
• Complete plugin suite: 13 files, 413 tests passed, zero failed.
• Real installation/activation: passed in a temporary profile, including installed-file comparison with committed source and external-provider activation.
• Selected correctness lint and diff whitespace: passed.

Skipped checks and limits

• Repository-wide Python, native, SDK, and web suites: not run because this change is confined to the Hermes memory-provider plugin and changes none of those components.
• Full Ruff formatting/lint and mypy: not run for the large existing plugin files; validation was limited to the correctness rules shown above to keep this small plugin change focused. Broad style/type validation is not claimed.
• Linux/Windows, alternate Hermes release hosts, and the real Quick Local service matrix: not run locally; local validation used macOS and the pinned main test host. Connection, installation, and service lifecycle code are unchanged.
• Live remote-server retrieval/extraction and a full interactive Hermes session: not run; provider tests use controlled client responses, and the install check validates installation/activation only. No production or laptop upgrade acceptance is claimed.
• An external Claude review was attempted but could not run because its OAuth session had expired; a native self-review was completed instead.

GitHub showed no attached CI check results at the time of this description update. Local validation does not replace upstream CI or maintainer review.

Checklist

• My code follows the project's coding style — broad formatter/lint validation remains outstanding as noted above
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas — not applicable; the guard uses direct control flow and existing settings helpers
• I have made corresponding changes to the documentation
• My changes generate no new warnings — within the tests and selected correctness lint reported above
• Any dependent changes have been merged and published — not applicable; this PR requires no dependent code changes

Screenshots (if applicable)

Not applicable; this changes provider configuration and behavior, with no UI change.

Additional Notes

This is a backward-compatible, profile-wide opt-out. It does not introduce connection changes, a new compressor, or provider-disable behavior. The separate platform-specific proposal can independently gate the same automatic-prefetch boundary.

[timeleft--]

@ZaynJarvis, could you review this Hermes-plugin change? I routed it to you based on the integration guidance in CONTRIBUTING.md and your reviews of #5917, #5884, and #5374.

It adds a profile-wide auto_recall: false setting at the existing prefetch() boundary, so users can keep conversation capture and explicit memory tools without automatic historical-context injection. The default remains enabled. Fixes #6084 and complements #5893's platform-specific proposal.

The 67-line patch includes documentation and regression coverage. Six focused cases and all 413 plugin tests passed locally; the PR description contains the exact commands, installation evidence, skipped checks, and limitations. Could you confirm the configuration boundary and review the implementation? GitHub currently shows no CI checks on this fork PR; please also check whether the workflow needs maintainer approval.

I could not add a formal reviewer request because this contributor account lacks permission, so I am requesting review here.