Skip to content

Fix auto memory recall scoping#1968

Merged
rapids-bot[bot] merged 4 commits into
NVIDIA:release/1.7from
willkill07:wkk_auto_memory_recall_fix
May 19, 2026
Merged

Fix auto memory recall scoping#1968
rapids-bot[bot] merged 4 commits into
NVIDIA:release/1.7from
willkill07:wkk_auto_memory_recall_fix

Conversation

@willkill07
Copy link
Copy Markdown
Member

@willkill07 willkill07 commented May 19, 2026

Description

Closes NAT-270

Fix automatic memory recall for memory-backed agent workflows run across CLI invocations.

This updates the auto-memory wrapper to retrieve existing memory before storing the current user message, so recall questions do not pollute memory search before lookup. It also passes the console front end user_id and conversation_id into the runtime session, ensures direct session conversation metadata is scoped and reset correctly, and updates the Zep Cloud adapter to use query-based graph search before falling back to thread context. When no conversation ID is supplied, Zep now uses a deterministic per-user default thread instead of a single global fallback thread.

The root cause was a combination of memory operation ordering and runtime scoping gaps:

  • recall prompts were stored before retrieval
  • nat run did not propagate the configured console user or conversation ID
  • Zep adapter collapsed CLI runs without conversation IDs into default_zep_thread while retrieval depended on thread context.

Docs were updated to describe nat run --user_id, nat run --conversation_id, and the runtime scoping model for memory-backed workflows.

By Submitting this PR I confirm:

  • I am familiar with the Contributing Guidelines.
  • We require that all contributors "sign-off" on their commits. This certifies that the contribution is your original work, or you have rights to submit it under the same license, or a compatible license.
    • Any contribution which contains commits that are not Signed-Off will not be accepted.
  • When the PR is ready for review, new or existing tests cover these changes.
  • When the PR is ready for review, the documentation is up to date with these changes.

Validation

Automated checks run locally:

uv run pytest packages/nvidia_nat_langchain/tests/agent/test_auto_memory_wrapper.py packages/nvidia_nat_core/tests/nat/runtime/test_session_manager.py packages/nvidia_nat_zep_cloud/tests/test_zep_editor.py
uv run ruff check packages/nvidia_nat_langchain/src/nat/plugins/langchain/agent/auto_memory_wrapper/agent.py packages/nvidia_nat_langchain/tests/agent/test_auto_memory_wrapper.py packages/nvidia_nat_core/src/nat/front_ends/console/console_front_end_config.py packages/nvidia_nat_core/src/nat/front_ends/console/console_front_end_plugin.py packages/nvidia_nat_core/src/nat/runtime/session.py packages/nvidia_nat_core/tests/nat/runtime/test_session_manager.py packages/nvidia_nat_zep_cloud/src/nat/plugins/zep_cloud/zep_editor.py packages/nvidia_nat_zep_cloud/tests/test_zep_editor.py
git diff --check

Provided manual validation:

Seeding

$ nat run --config_file ./workflow.yml --input "My name is Will, and I live in Pennsylvania" --input "I wanted to let you know that I am a software engineer."

Retrieval

$ nat run --config_file ./workflow.yml --input "what is my name?" --input "what is my job?" --input "where do i live?"
...
2026-05-19 16:09:25 - INFO     - nat.runtime.session:329 - Shared workflow built (entry_function=None)
2026-05-19 16:09:52 - INFO     - nat.front_ends.console.console_front_end_plugin:160 - --------------------------------------------------
Workflow Result:
Will
You are a software engineer.
You live in Pennsylvania.
--------------------------------------------------

Summary by CodeRabbit

  • New Features

    • Added CLI options --user_id and --conversation_id and a console default user_id ("nat_run_user_id") to isolate sessions and memory-backed runs.
    • Zep Cloud now uses deterministic per-user thread IDs when conversation_id is absent.
  • Bug Fixes

    • Memory retrieval now runs before capturing the current user message so prior context is injected first.
  • Documentation

    • Updated multi-tenant memory isolation and CLI docs for runtime user ID extraction and new options.
  • Tests

    • Added tests for session context cleanup and memory retrieval ordering.

Review Change Stack

Signed-off-by: Will Killian <wkillian@nvidia.com>
@willkill07 willkill07 requested a review from a team as a code owner May 19, 2026 20:33
@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented May 19, 2026

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 072e0802-78a6-4f8d-89c0-7a5a70b5680e

📥 Commits

Reviewing files that changed from the base of the PR and between 3aa8038 and 96714e3.

📒 Files selected for processing (1)
  • packages/nvidia_nat_core/tests/nat/runtime/test_session_manager.py
✅ Files skipped from review due to trivial changes (1)
  • packages/nvidia_nat_core/tests/nat/runtime/test_session_manager.py

Walkthrough

This PR moves user and conversation ID extraction to runtime/front-ends and SessionManager.session(), adds conversation_id and user_message_id context-var lifecycle management, reorders auto-memory-wrapper to retrieve memory before capturing the current message, and implements deterministic per-user Zep thread-id fallback with corresponding tests and docs.

Changes

Runtime user/conversation ID and session context

Layer / File(s) Summary
Session context lifecycle for conversation metadata
packages/nvidia_nat_core/src/nat/runtime/session.py, packages/nvidia_nat_core/tests/nat/runtime/test_session_manager.py
SessionManager.session() initializes and resets conversation_id and user_message_id context variables on entry and exit using captured tokens; tests validate set/reset behavior.
Console front-end configuration and session integration
packages/nvidia_nat_core/src/nat/front_ends/console/console_front_end_config.py, packages/nvidia_nat_core/src/nat/front_ends/console/console_front_end_plugin.py
ConsoleFrontEndConfig adds optional conversation_id; ConsoleFrontEndPlugin reads user_id and conversation_id from front-end config and passes them into session_manager.session() for per-query and input-file flows.
Zep Cloud per-user thread ID generation with fallback
packages/nvidia_nat_zep_cloud/src/nat/plugins/zep_cloud/zep_editor.py, packages/nvidia_nat_zep_cloud/tests/test_zep_editor.py
ZepEditor uses NAT conversation_id for thread_id when present, otherwise generates a deterministic SHA-256 per-user default; search() uses graph.search to assemble memory and falls back to thread.get_user_context when graph results are empty.
Auto-memory-wrapper retrieval before capture execution order
packages/nvidia_nat_langchain/src/nat/plugins/langchain/agent/auto_memory_wrapper/agent.py, packages/nvidia_nat_langchain/tests/agent/test_auto_memory_wrapper.py
StateGraph reorders edges to execute memory_retrieve before capture_user_message when retrieval is enabled; tests assert search occurs before add_items and that retrieved memory appears before the current user query.
Documentation updates for runtime user/conversation ID extraction
docs/source/build-workflows/memory.md, docs/source/components/agents/auto-memory-wrapper/auto-memory-wrapper.md, docs/source/reference/cli.md, examples/agents/auto_memory_wrapper/README.md
Docs updated to specify runtime user_id via SessionManager.session(), X-User-ID, or nat run --user_id; add --conversation_id CLI option and update examples and important notes to reflect runtime/front-end scoping and Zep Cloud deterministic thread behavior.
CI path-check allowlist
ci/scripts/path_checks.py
Adds runtime/front-end to allowlist to prevent path-check failures.

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly and concisely describes the main change: fixing auto memory recall scoping, which is the root issue addressed across all code and documentation changes in the PR.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Comment @coderabbitai help to get the list of available commands and usage tips.

@willkill07 willkill07 self-assigned this May 19, 2026
@willkill07 willkill07 added bug Something isn't working non-breaking Non-breaking change labels May 19, 2026
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
docs/source/reference/cli.md (1)

536-538: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Sync nat run --help options with nat start console --help.

Line 536-Line 538 still describe --input_file as JSON input and do not include --user_id / --conversation_id, which now appear in Line 238-Line 247. Since nat run is documented as an alias, this section should match to avoid conflicting CLI guidance.

As per coding guidelines, “Ensure the nat run CLI docs remain consistent with the console front-end options.”

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/source/reference/cli.md` around lines 536 - 538, Update the `nat run`
help block so it matches the `nat start console` options: change the
`--input_file` description to the same wording used in the console docs (do not
restrict it to "json" if console accepts other structured formats), and add the
`--user_id` and `--conversation_id` option entries with the same descriptions as
in the `nat start console --help` section; ensure the help text for `nat run`
(alias) references the same flags `--input_file`, `--user_id`, and
`--conversation_id` and uses identical wording to avoid conflicting CLI
guidance.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/nvidia_nat_core/tests/nat/runtime/test_session_manager.py`:
- Line 466: Remove the unnecessary `@pytest.mark.asyncio` decorator from the new
async test (the line showing "`@pytest.mark.asyncio`") so the test relies on the
repo's auto-detection for async tests; if that decorator import is now unused,
also remove the unused pytest import/marker reference to keep imports clean.

---

Outside diff comments:
In `@docs/source/reference/cli.md`:
- Around line 536-538: Update the `nat run` help block so it matches the `nat
start console` options: change the `--input_file` description to the same
wording used in the console docs (do not restrict it to "json" if console
accepts other structured formats), and add the `--user_id` and
`--conversation_id` option entries with the same descriptions as in the `nat
start console --help` section; ensure the help text for `nat run` (alias)
references the same flags `--input_file`, `--user_id`, and `--conversation_id`
and uses identical wording to avoid conflicting CLI guidance.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: ad8754c2-2b7e-4f3c-9b58-002324754b57

📥 Commits

Reviewing files that changed from the base of the PR and between 70afb02 and da98259.

📒 Files selected for processing (12)
  • docs/source/build-workflows/memory.md
  • docs/source/components/agents/auto-memory-wrapper/auto-memory-wrapper.md
  • docs/source/reference/cli.md
  • examples/agents/auto_memory_wrapper/README.md
  • packages/nvidia_nat_core/src/nat/front_ends/console/console_front_end_config.py
  • packages/nvidia_nat_core/src/nat/front_ends/console/console_front_end_plugin.py
  • packages/nvidia_nat_core/src/nat/runtime/session.py
  • packages/nvidia_nat_core/tests/nat/runtime/test_session_manager.py
  • packages/nvidia_nat_langchain/src/nat/plugins/langchain/agent/auto_memory_wrapper/agent.py
  • packages/nvidia_nat_langchain/tests/agent/test_auto_memory_wrapper.py
  • packages/nvidia_nat_zep_cloud/src/nat/plugins/zep_cloud/zep_editor.py
  • packages/nvidia_nat_zep_cloud/tests/test_zep_editor.py

Comment thread packages/nvidia_nat_core/tests/nat/runtime/test_session_manager.py Outdated
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Signed-off-by: Will Killian <2007799+willkill07@users.noreply.github.com>
Signed-off-by: David Gardner <dagardner@nvidia.com>
Signed-off-by: David Gardner <dagardner@nvidia.com>
@dagardner-nv
Copy link
Copy Markdown
Contributor

/merge

@rapids-bot rapids-bot Bot merged commit 1885e46 into NVIDIA:release/1.7 May 19, 2026
16 of 17 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working non-breaking Non-breaking change

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants