feat(message_history): add async methods to MessageHistory - #816

Branch: feat/message-history-async (fork Yarmoluk/redis-vl-python), rebased onto main at 506b961 (includes #792 and #785).
Commits: 82f91e4 feat, 93657d7 docs, c1b5d75 test. Label: auto:minor.

Summary

Follow-up to #784, which gave SemanticRouter aroute / aroute_many. MessageHistory had the same gap: an agent running on asyncio blocked its event loop on every history read or write. This PR adds the async twins -- aget_recent, astore, aadd_messages, aadd_message, acount, adrop, aclear, adisconnect and an aindex property -- using the same pattern #784 landed:

• The AsyncSearchIndex is built lazily on the first async call, from the sync index's connection settings. A history built from redis_url gets its own async connection from that URL and connection_kwargs; a history given a sync redis_client gets an async client converted from that client's connection settings by RedisConnectionFactory.sync_to_async_redis, owned by the async index, so adisconnect closes only the converted client and the caller's sync client is never touched or rebuilt.
• Every async method goes through the AsyncSearchIndex; none reaches into a Redis client directly (adrop deletes with aindex.drop_keys(aindex.key(id))).
• Query building (_recent_query, _count_query) and message construction (_chat_messages, _exchange) move into helpers shared by the sync and async paths, so the two cannot drift.
• The docstrings say what is and is not supported, in the router's wording: since fix(connection): convert TLS and unix-socket clients to async #792 a sync client over TLS or a unix socket converts; Sentinel and Redis Cluster clients do not (pass redis_url instead); the async client is bound to the loop that made the first call, so call adisconnect before switching loops.

No sync behaviour changes. SemanticMessageHistory is not covered here (see Notes).

Reviewer Brief

Start here: redisvl/extensions/message_history/message_history.py, _get_async_index() (line 418). Every async method goes through it, and it decides whether the async index connects from the URL the sync index owns or from a client converted from the caller's sync client; it is the same code as SemanticRouter._get_async_index.

Where it could fail

• message_history.py:432: a caller-supplied Sentinel or Cluster client, or one with a sync-only setting such as ssl_validate_ocsp=True, raises ValueError from sync_to_async_redis at the first async call; the aget_recent docstring names Sentinel and Cluster but, like the router's, not the sync-only-setting case.
• message_history.py:154: adrop removes the key with UNLINK (via drop_keys) where sync drop uses DEL; both are @keyspace @write, but an ACL that grants +del by name and not +unlink would allow drop and deny adrop (UNLINK, DEL).
• message_history.py:449: the async client belongs to the loop that made the first call; a second asyncio.run() on the same history without adisconnect in between fails, the same contract SemanticRouter has shipped since feat(router): add async aroute and aroute_many to SemanticRouter #784.

Not verified: Redis Cluster and Sentinel (no cluster tests run locally or in CI); the TLS and unix-socket conversion paths were not exercised end to end through MessageHistory (they are covered by #792's own tests); connection_kwargs and lib_name forwarding on the URL path is not asserted by a test.

Beyond CI: each of these mutations makes test_async_message_history_matches_sync fail: astore ignoring session_tag, adrop going through the sync client, adrop(id) ignoring id, the async index rebuilt per call, and adisconnect not closing the converted client. The two new integration tests pass locally against redis:8.4 via testcontainers.

Since the last brief: rebased onto 506b961 (#792 now converts TLS and unix-socket clients, so the caveat narrows to Sentinel and Cluster); adrop deletes through aindex.drop_keys instead of the async client; the sync-equivalence test now blocks the sync client's execute_command and pipeline, seeds a second session with astore, and pins tool_call_id/metadata, adrop(id), async-index reuse and adisconnect closing the converted pool.

_{Reviewed c1b5d75 · Claude Code (claude-opus-5-5) · lenses: correctness, security, design, tests, docs, Redis behaviour}

Test plan

Run on the rebased branch at c1b5d75, macOS, uv, Docker running (testcontainers starts redis:8.4):

make format
# All done! ✨ 🍰 ✨
# 272 files left unchanged.

rm -rf .mypy_cache && make check-types
# Success: no issues found in 122 source files

uv run pytest tests/integration/test_message_history.py -k async_message_history -q -p no:cacheprovider
# 2 passed, 33 deselected

uv run pytest -n auto tests/integration/test_message_history.py tests/unit -q -p no:cacheprovider
# 3 failed, 1500 passed, 9 skipped, 53 errors

The 3 failures and 53 errors are the identical set on main at 506b961: every one is ModuleNotFoundError: sentence_transformers (the HuggingFace vectorizer is not installed locally), in SemanticMessageHistory tests this PR does not touch.

test_async_message_history_matches_sync takes its expected values from the sync methods, then patches execute_command and pipeline on the sync index's Redis client to raise, so any async method that made a blocking call would fail it. test_async_message_history_with_redis_url checks that a URL-built history builds its async index from that URL rather than converting the client.

Notes

• SemanticMessageHistory gets no async methods in this PR. Its get_relevant embeds through the vectorizer, which brings in the aembed caveats feat(router): add async aroute and aroute_many to SemanticRouter #784 documented for the router; it is a separate change with its own brief.
• No adelete: dropping the index is setup/teardown rather than a per-turn call, and feat(router): add async aroute and aroute_many to SemanticRouter #784 drew the same line for the router. No async form of the messages property either, since a property cannot be awaited; aget_recent with a large top_k is the async read.
• Loop binding follows feat(router): add async aroute and aroute_many to SemanticRouter #784's adisconnect contract rather than the rebuild-on-new-loop fix(vectorize): use Cohere's async client for aembed and aembed_many #785 added for Cohere's async client. The async index owns a connection pool, and rebuilding it silently on a loop change would leak the previous pool; an explicit adisconnect keeps the two extensions consistent and the close visible.
• _get_async_index, aindex and adisconnect match SemanticRouter's line for line; they are kept as two copies rather than a shared helper, since extracting one would mean changing the merged router code in this PR.
• count/acount keep the sync method's unannotated signature rather than adding -> int to one twin only.