NAMS: well-known endpoint, X-Workspace-Id fix, live-integration test scaffold (#136)

* feat: NAMS well-known endpoint, X-Workspace-Id header fix, live-integration test scaffold

A live NAMS SaaS account became available mid-session, revealing that an account-wide API
key needs X-Workspace-Id (a workspace-scoped key carries it implicitly) -- NamsOptions.WorkspaceId
was captured but never attached. Adds NamsWellKnown.Endpoint (the public SaaS base URL, non-secret)
and a skip-cleanly live-integration test scaffold that validates the full Phase 4-6 pipeline
(identity resolution -> persistence -> recall) against the real service for the first time.

* fix: self-review findings from live-validation branch (WorkspaceId validation, poll resilience, conventions)

- Add NamsOptionValidator.HasValidWorkspaceId: fail fast on control characters instead of a
  lazy FormatException on the first HTTP call.
- PollUntilAsync now swallows exceptions from the polled condition itself (not just the delay),
  matching Neo4jIntegrationFixture.WaitForVectorIndexesAsync's established pattern -- a transient
  blip against the live service no longer aborts the whole bounded poll.
- Drop the redundant second Category trait, remove ConfigureAwait(false) from test code, and
  match NamsLiveTestCollection's shape to its one direct precedent (Neo4jIntegrationCollection).

Author: joslat

docs/reviews/NAMS_LiveValidationAndIntegrationTestScaffold_PlanningAndImplementationPlan.md

@@ -0,0 +1,108 @@
+# NAMS Live Validation & Integration Test Scaffold — Planning and Implementation Plan
+
+**Prepared:** 2026-07-17
+**Branch:** `nams/live-validation-integration-tests`
+**Purpose:** Not one of the engineering plan's numbered phases -- this is a small, opportunistic follow-up
+that became possible mid-session when a live NAMS SaaS account and API key were provisioned. It closes two
+concrete gaps Phases 1-6 could only leave as documented unknowns (no live sandbox existed yet), and adds a
+skip-cleanly live-integration test scaffold so the whole Phase 4-6 pipeline (identity resolution -> recall ->
+persistence) is now verified against the real service, not just deterministic fakes.
+
+## 1. Trigger and scope
+
+Mid-session, a live NAMS SaaS account became available (`memory.neo4jlabs.com`), including a dedicated,
+isolated `agent-memory-dotnet-dev` workspace (with its own free, auto-expiring managed database) created
+specifically so live testing never touches a production/real workspace. Comparing the actual authenticated
+API docs against the existing `AgentMemory.Nams` client surfaced two small, concrete findings:
+
+1. The real public SaaS base URL/auth contract matches Phase 2's guessed-from-public-docs shapes almost
+   exactly (conversations, messages, messages/bulk, entities/search, context) -- no client-shape bugs found.
+2. `NamsOptions.WorkspaceId` was captured in configuration but never actually attached as a request header --
+   harmless for a workspace-scoped API key (which carries its workspace implicitly), but a real gap for an
+   account-wide (admin) key, which needs `X-Workspace-Id` to target a specific workspace.
+
+**In scope:**
+- `NamsWellKnown.Endpoint` -- a non-secret constant for the public SaaS base URL, so consuming code/tests
+  don't need an env var for something that's the same for everyone.
+- The `X-Workspace-Id` header fix in `NamsClientFactory.ConfigureHttpClient`.
+- A live-integration test scaffold (env-var-gated, skips cleanly and never runs in CI) exercising the full
+  public surface (`INamsConversationResolver` -> `INamsPersistenceService` -> `INamsRecallService`) against
+  the real, isolated dev workspace.
+
+**Explicitly out of scope** (not triggered by this work):
+- Engineering plan Phase 7 (backend-neutral convergence) -- still gated on its own entry criteria, unrelated
+  to this.
+- Phase 8 (MCP/capability-aware tools), Phase 9 (observability), the rest of Phase 10 (contract tests, HTTP
+  simulation, TCK Platinum), Phase 11 (sample) -- untouched by this branch.
+- `SearchMessagesAsync`/`POST /v1/conversations/{id}/search` -- now confirmed to exist in the live API (it
+  was dropped from Phase 2's `INamsClient` for lack of confirmation), but adding it is a separate, later
+  decision, not bundled into this opportunistic fix.
+
+## 2. Changes
+
+- `src/AgentMemory.Nams/NamsWellKnown.cs` (new) -- `public static class NamsWellKnown { public static readonly
+  Uri Endpoint = new("https://memory.neo4jlabs.com/v1"); }`.
+- `src/AgentMemory.Nams/Client/NamsClientFactory.cs` (modified) -- `ConfigureHttpClient` now adds an
+  `X-Workspace-Id` default request header when `NamsOptions.WorkspaceId` is set (a static header, unlike the
+  per-request-refreshed `Authorization` header `NamsAuthenticationHandler` attaches).
+- `tests/AgentMemory.Tests.Unit/Nams/NamsWellKnownTests.cs` (new) -- 1 test.
+- `tests/AgentMemory.Tests.Unit/Nams/NamsClientFactoryTests.cs` (modified) -- 2 new tests (header present when
+  `WorkspaceId` set; absent when not).
+- `tests/AgentMemory.Tests.Integration/Nams/` (new) -- live-integration test scaffold:
+  - `NamsLiveCredentials.cs` -- reads `NAMS_API_KEY`/`NAMS_DEV_WORKSPACE_ID` from the environment, with a
+    Windows `EnvironmentVariableTarget.User` registry fallback so a credential set mid-session doesn't
+    require restarting the IDE/terminal to become visible.
+  - `LiveNamsFactAttribute.cs` -- a `[Fact]` variant that sets `Skip` at discovery time when credentials
+    aren't available. CI still discovers these tests (same `Category=Integration` trait as every other
+    integration test) but they report as Skipped there and never fail the build.
+  - `NamsLiveFixture.cs` + `NamsLiveTestCollection.cs` -- a real DI container wired via
+    `AddNamsAgentMemory`, exactly as a consuming application would.
+  - `NamsLiveConnectivityTests.cs` -- 3 tests: conversation creation, persist-then-recall round trip, and a
+    message-with-a-known-entity round trip (bounded polling for NAMS's asynchronous extraction, never
+    unbounded per the plan's own Phase 10 release gate). Every identity uses a fresh GUID ("unique test user
+    prefix" per Phase 10).
+- `tests/AgentMemory.Tests.Integration/AgentMemory.Tests.Integration.csproj` (modified) -- added a
+  `ProjectReference` to `AgentMemory.Nams`.
+
+## 3. Verification so far
+
+- `dotnet test tests/AgentMemory.Tests.Unit --filter "FullyQualifiedName~Nams"` -- 162/162 green.
+- `dotnet build tests/AgentMemory.Tests.Integration` -- 0 warnings, 0 errors.
+- `dotnet test tests/AgentMemory.Tests.Integration --filter "FullyQualifiedName~Nams.NamsLiveConnectivityTests"`
+  -- **all 3 live tests passed against the real NAMS SaaS**, ~10s total. First-ever live validation of the
+  Phase 4-6 pipeline end to end.
+
+## 4. Self-review findings and fixes
+
+3 parallel reviewers (correctness / cross-file impact / cleanup-conventions), matching the Phase 4-6 pattern:
+
+- **Correctness (2 fixed):** `PollUntilAsync` didn't catch exceptions from the polled condition itself (only
+  from the delay) -- a single transient blip against the live service during the 30-60s window would abort
+  the whole poll instead of retrying through the remaining budget. Fixed to swallow and keep polling, matching
+  `Neo4jIntegrationFixture.WaitForVectorIndexesAsync`'s established pattern. Separately, `NamsOptions.WorkspaceId`
+  had no fail-fast validation like every other option -- a stray control character (e.g. a pasted trailing
+  newline) would throw lazily on the first HTTP request instead of a clear `OptionsValidationException` at
+  startup. Added `NamsOptionValidator.HasValidWorkspaceId` + 2 tests.
+- **Cross-file impact (0 fixed, 1 clarified):** confirmed no existing `AddNamsAgentMemory` caller sets
+  `WorkspaceId`, so the new header is a no-op for every pre-existing path; confirmed the manifest/CI
+  consistency check is directory-driven (no update needed for a file added inside an existing package);
+  re-ran and confirmed the doc's own test-count claims. Flagged (not a bug) that the new tests' trait would
+  make CI *discover* them, not silently exclude them -- addressed by removing the redundant second trait (see
+  below) and correcting this doc's wording.
+- **Cleanup/conventions (3 fixed):** dropped the redundant `[Trait("Category","LiveNams")]` (every other test
+  class in the project uses exactly one Category trait); removed `ConfigureAwait(false)` from the new test
+  code (CA2007 is `src/`-only, no sibling integration test uses it); changed `NamsLiveTestCollection` to the
+  brace-bodied non-sealed form matching its one direct precedent, `Neo4jIntegrationCollection`.
+
+Re-verified after fixes: 164/164 Nams unit tests green (162 + 2 new `WorkspaceId` validation tests), live
+suite still 3/3 green.
+
+## 5. Definition of done
+
+- [x] Live connectivity confirmed.
+- [x] `X-Workspace-Id` gap fixed and covered.
+- [x] `NamsWellKnown` added and covered.
+- [x] Live-integration test scaffold built and passing against the real service.
+- [x] Self-reviewed and fixes applied.
+- [ ] PR opened, CI green (live tests are discovered but report Skipped there -- no credentials in CI),
+      merged to `main`.

src/AgentMemory.Nams/Client/NamsClientFactory.cs

@@ -8,6 +8,12 @@ public static void ConfigureHttpClient(HttpClient httpClient, NamsOptions option
     {
         httpClient.BaseAddress = NormalizeBaseAddress(options.Endpoint);
         httpClient.Timeout = options.RequestTimeout;
+
+        // Only an account-wide (admin) API key needs this -- a workspace-scoped key already carries its
+        // workspace implicitly. Static for the client's lifetime (unlike Authorization, which is refreshed
+        // per-request by NamsAuthenticationHandler): a workspace binding never expires mid-session.
+        if (!string.IsNullOrWhiteSpace(options.WorkspaceId))
+            httpClient.DefaultRequestHeaders.Add("X-Workspace-Id", options.WorkspaceId);
     }
 
     /// <summary>

src/AgentMemory.Nams/Internal/NamsOptionValidator.cs

@@ -51,4 +51,14 @@ options.Endpoint is null
     /// all can never successfully authenticate a request.
     /// </summary>
     public static bool HasApiKey(NamsOptions options) => !string.IsNullOrWhiteSpace(options.ApiKey);
+
+    /// <summary>
+    /// True when <see cref="NamsOptions.WorkspaceId"/> is unset (it's optional -- a workspace-scoped API key
+    /// carries its workspace implicitly; only an account-wide key needs this set) or contains no control
+    /// characters. It is sent verbatim as the <c>X-Workspace-Id</c> header by
+    /// <see cref="Client.NamsClientFactory.ConfigureHttpClient"/>; a stray CR/LF would otherwise throw a
+    /// <see cref="FormatException"/> lazily on the first HTTP request instead of failing fast here at startup.
+    /// </summary>
+    public static bool HasValidWorkspaceId(NamsOptions options) =>
+        options.WorkspaceId is null || !options.WorkspaceId.Any(char.IsControl);
 }

src/AgentMemory.Nams/NamsServiceCollectionExtensions.cs

@@ -39,6 +39,7 @@ public static IServiceCollection AddNamsAgentMemory(
             .Validate(NamsOptionValidator.HasNonNegativeMaxRetryAttempts, "NamsOptions.MaxRetryAttempts must be non-negative.")
             .Validate(NamsOptionValidator.HasNonNegativeInitialRetryDelay, "NamsOptions.InitialRetryDelay must be non-negative.")
             .Validate(NamsOptionValidator.HasApiKey, "NamsOptions.ApiKey must be provided (JWT/Auth0 authentication is not yet supported).")
+            .Validate(NamsOptionValidator.HasValidWorkspaceId, "NamsOptions.WorkspaceId must not contain control characters.")
             .ValidateOnStart();
 
         // Idempotent by construction: TryAddSingleton means a second AddNamsAgentMemory call is a

src/AgentMemory.Nams/NamsWellKnown.cs

@@ -0,0 +1,12 @@
+namespace AgentMemory.Nams;
+
+/// <summary>
+/// Well-known, non-secret values for the public NAMS SaaS at <c>memory.neo4jlabs.com</c>. Only applicable
+/// when targeting that public service -- a self-hosted or otherwise-deployed NAMS-compatible endpoint must
+/// set <see cref="NamsOptions.Endpoint"/> to its own address instead.
+/// </summary>
+public static class NamsWellKnown
+{
+    /// <summary>The public NAMS SaaS REST API base endpoint.</summary>
+    public static readonly Uri Endpoint = new("https://memory.neo4jlabs.com/v1");
+}

tests/AgentMemory.Tests.Integration/AgentMemory.Tests.Integration.csproj

@@ -34,6 +34,7 @@
     <ProjectReference Include="..\..\src\AgentMemory.Abstractions\AgentMemory.Abstractions.csproj" />
     <ProjectReference Include="..\..\src\AgentMemory.McpServer\AgentMemory.McpServer.csproj" />
     <ProjectReference Include="..\..\src\AgentMemory.AgentFramework\AgentMemory.AgentFramework.csproj" />
+    <ProjectReference Include="..\..\src\AgentMemory.Nams\AgentMemory.Nams.csproj" />
     <ProjectReference Include="..\..\tools\AgentMemory.TckBridge\AgentMemory.TckBridge.csproj" />
   </ItemGroup>
 

tests/AgentMemory.Tests.Integration/Nams/LiveNamsFactAttribute.cs

@@ -0,0 +1,16 @@
+namespace AgentMemory.Tests.Integration.Nams;
+
+/// <summary>
+/// A <see cref="FactAttribute"/> that skips at discovery time when <see cref="NamsLiveCredentials.IsAvailable"/>
+/// is <see langword="false"/>. These tests call the real NAMS SaaS and must never run in CI or on a machine
+/// without an isolated dev workspace configured (engineering plan Phase 10: "never run against production
+/// customer workspaces").
+/// </summary>
+public sealed class LiveNamsFactAttribute : FactAttribute
+{
+    public LiveNamsFactAttribute()
+    {
+        if (!NamsLiveCredentials.IsAvailable)
+            Skip = "Live NAMS credentials not configured (NAMS_API_KEY / NAMS_DEV_WORKSPACE_ID) -- skipping live NAMS test.";
+    }
+}

tests/AgentMemory.Tests.Integration/Nams/NamsLiveConnectivityTests.cs

@@ -0,0 +1,138 @@
+using System.Runtime.CompilerServices;
+using Microsoft.Extensions.DependencyInjection;
+using FluentAssertions;
+using AgentMemory.Nams.Identity;
+using AgentMemory.Nams.Persistence;
+using AgentMemory.Nams.Recall;
+
+namespace AgentMemory.Tests.Integration.Nams;
+
+/// <summary>
+/// Live round-trip tests against the real NAMS SaaS (<c>memory.neo4jlabs.com</c>), exercised entirely
+/// through the public surface (<see cref="INamsConversationResolver"/>, <see cref="INamsPersistenceService"/>,
+/// <see cref="INamsRecallService"/>) -- the same contract <c>NamsMemoryContextProvider</c> (Phase 6) uses
+/// internally. Every identity is a fresh GUID (engineering plan Phase 10: "unique test user prefix"), and
+/// these only ever run against the isolated <c>agent-memory-dotnet-dev</c> workspace -- never a production
+/// customer workspace. <see cref="LiveNamsFactAttribute"/> skips cleanly when
+/// NAMS_API_KEY/NAMS_DEV_WORKSPACE_ID aren't configured -- CI still discovers these tests (they carry the
+/// same <c>Category=Integration</c> trait as every other integration test), but they report as Skipped
+/// there and never fail the build.
+/// </summary>
+[Collection("NAMS Live")]
+[Trait("Category", "Integration")]
+public sealed class NamsLiveConnectivityTests
+{
+    private readonly NamsLiveFixture _fixture;
+
+    public NamsLiveConnectivityTests(NamsLiveFixture fixture) => _fixture = fixture;
+
+    [LiveNamsFact]
+    public async Task ResolveAsync_NewIdentity_CreatesConversation()
+    {
+        var resolver = _fixture.Services!.GetRequiredService<INamsConversationResolver>();
+
+        var result = await resolver.ResolveAsync(UniqueIdentity(), CancellationToken.None);
+
+        result.WasCreated.Should().BeTrue();
+        result.NamsConversationId.Should().NotBeNullOrWhiteSpace();
+    }
+
+    [LiveNamsFact]
+    public async Task PersistTurnAsync_ThenRecallAsync_EventuallyReturnsThePersistedMessage()
+    {
+        var services = _fixture.Services!;
+        var resolver = services.GetRequiredService<INamsConversationResolver>();
+        var persistence = services.GetRequiredService<INamsPersistenceService>();
+        var recall = services.GetRequiredService<INamsRecallService>();
+
+        var conversation = await resolver.ResolveAsync(UniqueIdentity(), CancellationToken.None);
+
+        var marker = $"NAMS live test marker {Guid.NewGuid():N}: John works at Acme Corp in Denver.";
+        var persistResult = await persistence.PersistTurnAsync(
+            conversation.NamsConversationId,
+            userMessages: [new NamsMessageToPersist(marker)],
+            assistantMessages: [],
+            CancellationToken.None);
+
+        persistResult.Outcome.Should().Be(NamsPersistenceOutcome.Persisted);
+
+        // Bounded poll -- NAMS ingestion/extraction is asynchronous. Never unbounded (Phase 10 release gate
+        // explicitly rejects unbounded eventual-consistency waits).
+        var found = await PollUntilAsync(
+            async () =>
+            {
+                var recalled = await recall.RecallAsync(conversation.NamsConversationId, marker, CancellationToken.None);
+                return recalled.Items.Any(i => i.Content.Contains(marker, StringComparison.Ordinal));
+            },
+            timeout: TimeSpan.FromSeconds(30));
+
+        found.Should().BeTrue("the just-persisted message should surface in recall's recent-messages tier");
+    }
+
+    [LiveNamsFact]
+    public async Task PersistTurnAsync_MessageWithKnownEntity_EventuallyExtractsIt()
+    {
+        var services = _fixture.Services!;
+        var resolver = services.GetRequiredService<INamsConversationResolver>();
+        var persistence = services.GetRequiredService<INamsPersistenceService>();
+        var recall = services.GetRequiredService<INamsRecallService>();
+
+        var conversation = await resolver.ResolveAsync(UniqueIdentity(), CancellationToken.None);
+        var entityName = $"Acme-{Guid.NewGuid():N}".Substring(0, 12);
+
+        await persistence.PersistTurnAsync(
+            conversation.NamsConversationId,
+            userMessages: [new NamsMessageToPersist($"John works at {entityName} Corp in Denver.")],
+            assistantMessages: [],
+            CancellationToken.None);
+
+        // Entity extraction runs asynchronously server-side and can lag well behind ingestion.
+        var found = await PollUntilAsync(
+            async () =>
+            {
+                var recalled = await recall.RecallAsync(conversation.NamsConversationId, entityName, CancellationToken.None);
+                return recalled.Items.Any(i => i.Content.Contains(entityName, StringComparison.Ordinal));
+            },
+            timeout: TimeSpan.FromSeconds(60));
+
+        found.Should().BeTrue($"an entity named '{entityName}' should eventually be extracted and recallable");
+    }
+
+    private static NamsConversationIdentity UniqueIdentity([CallerMemberName] string testName = "") => new()
+    {
+        ApplicationId = "agent-memory-dotnet-live-tests",
+        UserId = $"test-{testName}-{Guid.NewGuid():N}",
+        SessionId = Guid.NewGuid().ToString("N"),
+        LocalConversationId = Guid.NewGuid().ToString("N")
+    };
+
+    /// <summary>
+    /// Bounded poll helper -- never waits longer than <paramref name="timeout"/>. Swallows exceptions from
+    /// <paramref name="condition"/> itself (a live HTTP call can hit a transient blip mid-poll) and keeps
+    /// retrying within the remaining budget, matching <c>Neo4jIntegrationFixture.WaitForVectorIndexesAsync</c>'s
+    /// established pattern for this repo's other eventual-consistency polls.
+    /// </summary>
+    private static async Task<bool> PollUntilAsync(Func<Task<bool>> condition, TimeSpan timeout)
+    {
+        using var cts = new CancellationTokenSource(timeout);
+        while (!cts.IsCancellationRequested)
+        {
+            try
+            {
+                if (await condition())
+                    return true;
+            }
+            catch { /* transient failure against a live external service -- ignore and keep polling */ }
+
+            try
+            {
+                await Task.Delay(TimeSpan.FromSeconds(2), cts.Token);
+            }
+            catch (OperationCanceledException)
+            {
+                return false;
+            }
+        }
+        return false;
+    }
+}

tests/AgentMemory.Tests.Integration/Nams/NamsLiveCredentials.cs

@@ -0,0 +1,29 @@
+namespace AgentMemory.Tests.Integration.Nams;
+
+/// <summary>
+/// Reads live NAMS SaaS credentials for the isolated dev/test workspace from the environment. On Windows,
+/// falls back to a User-scope read when the process environment block doesn't have the variable --
+/// <see cref="Environment.GetEnvironmentVariable(string)"/> only sees what existed when the current process
+/// started, so a credential set after the IDE/terminal launched would otherwise require a full restart to
+/// become visible here.
+/// </summary>
+internal static class NamsLiveCredentials
+{
+    public static string? ApiKey => Read("NAMS_API_KEY");
+
+    public static string? WorkspaceId => Read("NAMS_DEV_WORKSPACE_ID");
+
+    /// <summary>
+    /// <see langword="true"/> only when both credentials are present. Tests gate on this via
+    /// <see cref="LiveNamsFactAttribute"/> so they skip cleanly instead of failing on machines/CI runs that
+    /// (correctly) have no live NAMS access -- these must never run against a shared/production workspace.
+    /// </summary>
+    public static bool IsAvailable => !string.IsNullOrWhiteSpace(ApiKey) && !string.IsNullOrWhiteSpace(WorkspaceId);
+
+    private static string? Read(string name)
+    {
+        var value = Environment.GetEnvironmentVariable(name);
+        if (!string.IsNullOrWhiteSpace(value)) return value;
+        return OperatingSystem.IsWindows() ? Environment.GetEnvironmentVariable(name, EnvironmentVariableTarget.User) : null;
+    }
+}