DO NOT MERGE: Add optional NeMo Flow integration#114
Draft
afourniernv wants to merge 1 commit into
Draft
Conversation
|
@afourniernv is attempting to deploy a commit to the lyonwj's projects Team on Vercel. A member of the Team first needs to authorize it. |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
There was a problem hiding this comment.
Pull request overview
Adds an optional NeMo Flow integration layer to Neo4j Agent Memory, enabling automatic recall/capture and NeMo Flow scope/event observability around instrumented (non-streaming) LLM executions while keeping Neo4j Agent Memory responsible for identity, filtering, storage, and formatting.
Changes:
- Introduces a public
neo4j_agent_memory.integrations.nemo_flowfacade plus private adapter modules for request/response shaping, identity resolution, telemetry, recall, and capture. - Adds optional dependency extra (
neo4j-agent-memory[nemo-flow]), an example script, and unit/example/integration smoke tests. - Documents the integration and links it into the integrations docs index + navigation.
Reviewed changes
Copilot reviewed 15 out of 16 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| uv.lock | Locks nemo-flow package artifacts and wires the new nemo-flow extra into the lock metadata. |
| pyproject.toml | Adds nemo-flow optional dependency extra (Python ≥ 3.11). |
| src/neo4j_agent_memory/integrations/init.py | Exposes nemo_flow from the integrations package namespace. |
| src/neo4j_agent_memory/integrations/nemo_flow.py | Public facade: install/uninstall handle and memory_scope context manager. |
| src/neo4j_agent_memory/integrations/_nemo_flow_types.py | Shared dataclasses/enums/config/registries for scopes/events and identity types. |
| src/neo4j_agent_memory/integrations/_nemo_flow_runtime.py | Lazy NeMo Flow import, identity-from-scope metadata, and telemetry helpers. |
| src/neo4j_agent_memory/integrations/_nemo_flow_memory.py | Neo4j memory access layer (context building + message storage). |
| src/neo4j_agent_memory/integrations/_nemo_flow_intercept.py | NeMo Flow LLM execution intercept orchestrating recall/capture + emitting scopes/events. |
| src/neo4j_agent_memory/integrations/_nemo_flow_content.py | Extracts query/interaction, formats context, injects system message into request content. |
| tests/unit/integrations/test_nemo_flow.py | Unit tests using a fake NeMo Flow runtime to validate install, identity, recall/capture, and observability events. |
| tests/examples/test_nemo_flow_memory.py | Smoke test that loads and runs the example module when nemo_flow is installed. |
| tests/integration/test_nemo_flow_integration.py | Live smoke test through real NeMo Flow + real Neo4j memory fixture. |
| examples/nemo_flow_memory.py | No-external-services demo showing install + memory_scope + instrumented execute path. |
| docs/modules/ROOT/pages/how-to/integrations/nemo-flow.adoc | New how-to page describing installation, behavior, customization, and observability contract. |
| docs/modules/ROOT/pages/how-to/integrations/index.adoc | Adds NeMo Flow integration to the integrations index and quickstart snippets. |
| docs/modules/ROOT/nav.adoc | Adds NeMo Flow to the documentation navigation. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+195
to
+197
| if accepts_positional_query(method): | ||
| return await self.invoke(method, query, **kwargs) | ||
| return await self.invoke(method, query=query, **kwargs) |
Comment on lines
+122
to
+132
| if not parts and hasattr(self.memory, "get_context"): | ||
| context = await self._invoke_get_context( | ||
| self.memory.get_context, | ||
| query, | ||
| session_id=session_id, | ||
| ) | ||
| return coerce_recall_context( | ||
| context, | ||
| NemoFlowContextSource.MEMORY_INTEGRATION, | ||
| metadata={"fallback_used": True}, | ||
| ) |
Comment on lines
+129
to
+130
| for key, value in identity.metadata().items(): | ||
| captured.setdefault(key, value) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
DO NOT MERGE
This is a draft PR for design review and live validation only. Please do not merge until the NeMo Flow integration shape, event contract, and memory provider boundaries have been reviewed.
What This Adds
Adds an optional NeMo Flow integration for Neo4j Agent Memory. The integration uses NeMo Flow as the hidden runtime/intercept layer while Neo4j Agent Memory owns memory identity, filtering, retrieval, formatting, and storage.
The intended user-facing DX is:
Application code does not need to import NeMo Flow directly for the common path, as long as the agent/framework LLM boundary is already flowing through NeMo Flow instrumentation.
Integration Behavior
Before an LLM call, the intercept:
memory_scope(...), or NeMo Flow scope metadataLLMRequestAfter the LLM call, the intercept:
MemoryIntegration.store_message(...)when availableclient.short_term.add_message(...)Architecture
The public module is kept intentionally small:
integrations/nemo_flow.py: public facade, install/uninstall handle, memory scope_nemo_flow_intercept.py: LLM execution orchestration_nemo_flow_memory.py: Neo4j Agent Memory access and storage_nemo_flow_runtime.py: lazy NeMo Flow import, scope identity, telemetry helpers_nemo_flow_content.py: request/response extraction and request mutation_nemo_flow_types.py: config, enums, registries, shared dataclassesObservability
The adapter emits NeMo Flow scopes for duration-bearing operations:
neo4j_agent_memory.memoryneo4j_agent_memory.recallneo4j_agent_memory.captureIt also emits mark events for state transitions:
neo4j_agent_memory.identity.resolvedneo4j_agent_memory.recall.context_builtneo4j_agent_memory.recall.injectedneo4j_agent_memory.recall.skippedneo4j_agent_memory.recall.failedneo4j_agent_memory.capture.extractedneo4j_agent_memory.capture.message_storedneo4j_agent_memory.capture.storedneo4j_agent_memory.capture.skippedneo4j_agent_memory.capture.failedScope and event payloads avoid raw user query text and recalled memory text. They include operational metadata such as counts, character lengths, insertion index, roles, and storage status.
Included Artifacts
neo4j-agent-memory[nemo-flow]Validation
Ran:
Result:
11 passed, Ruff clean.Known Limitations / Review Items