UAIX.UAI.Memory 1.0.4

UAIX.UAI

UAIX.UAI is the official UAIX-owned .NET package family for UAI-1 message envelopes and lightweight AI memory support. It provides strongly typed message models, JSON serialization helpers, safe routing-discovery clients, thread-safe memory stores for agents and applications, and .uaix desktop AI memory package manifest generation, validation, import, export, and bundle-switching helpers.

This workspace also includes UAIX.Talisman.AgentClient, a generic .NET connector for ecosystems that use the UAIX Talisman strategy. It is not site-specific: callers configure ecosystem keys, node keys, client base URLs, hub base URLs, and Talisman hub routes for their own runtime.

Install

dotnet add package UAIX.UAI --version 1.0.4
dotnet add package UAIX.UAI.Memory --version 1.0.4
dotnet add package UAIX.UAI.Abstractions --version 1.0.4
dotnet add package UAIX.Talisman.AgentClient --version 0.1.10

Use UAIX.UAI for the main UAI-1 message, routing, HTTP, .uaix, and runtime handoff surface. Use UAIX.UAI.Memory when an app only needs local AI memory stores. Use UAIX.UAI.Abstractions for shared interfaces and models in libraries that should avoid the heavier runtime dependency.

UAIX.UAI.Build is an MSBuild support package. Most applications do not need to reference it directly.

UAIX.Talisman.AgentClient is a separate package for ecosystems that use the UAIX Talisman strategy.

Use Talisman Protected-Anchor Checks

using UAIX.Talisman.AgentClient;

TalismanClientOptions options = TalismanClientOptions.FromEnvironment() with
{
    EcosystemKey = "my-ecosystem",
    NodeKey = "my-agent-node",
    ClientBaseUrl = "https://example.org"
};

TalismanAgentClient agent = new(options, enableHubClient: false);

GateDecision decision = agent.PrecheckToolCall(
    "delete_file",
    new Dictionary<string, object?> { ["path"] = ".uai/totem.uai" });

UAIX.Talisman.AgentClient treats .uai/totem.uai, .uai/taboo.uai, and .uai/talisman.uai as protected data. It records no-op evidence and request-only talk-back records; it does not approve changes, mutate protected anchors, validate credentials, certify runtime safety, or replace human review.

Create a UAI-1 Message

using System.Text.Json;
using UAIX.UAI.Core;

var body = JsonSerializer.SerializeToElement(new
{
    text = "Summarize the last support conversation.",
    intent = "summarize"
});

var message = UaiMessage.Create(
    profile: "agent.request",
    source: new Participant("agent", "support-copilot"),
    target: new Participant("service", "summary-api"),
    body: body);

var serializer = new UaiJsonSerializer();
var json = serializer.Serialize(message);
var roundTripped = serializer.Deserialize<UaiMessage>(json);

if (!roundTripped.IsValid)
{
    throw new InvalidOperationException(string.Join(Environment.NewLine, roundTripped.Validate()));
}

Use AI Memory

using UAIX.UAI.Memory;

var memory = new FileAgentMemory("agent-memory.json");

await memory.AddAsync("Customer prefers email updates.", category: "preference");
await memory.AddAsync("Open incident EN-1024 is waiting on billing details.", category: "case");

var matches = await memory.QueryAsync("billing");

InMemoryAgentMemory is useful for tests and short-lived processes. FileAgentMemory persists entries as JSON and uses asynchronous, thread-safe access. Both stores return defensive copies so callers cannot mutate the saved memory state accidentally.

Routing Discovery

UaixRoutingConfigClient fetches UAIX routing configuration from a configurable endpoint. The SDK does not make operating-system routing or network-stack changes; it exposes safe placeholders for future integrations that applications may opt into deliberately.

using UAIX.UAI.Core;

var client = new UaixRoutingConfigClient(httpClient);
var config = await client.FetchAsync(new Uri("https://uaix.org/.well-known/uai.json"));
var validateRoute = config.ResolveRoute("validate");

The routing client understands both compact UAIX .well-known route maps and explicit route arrays. Fetched configurations are validated for absolute HTTP/HTTPS endpoints before they are returned.

Send A Typed Message

using UAIX.UAI.Core;

var uai = new HttpUaiClient(httpClient);
var response = await uai.SendAsync(
    new Uri("https://uaix.org/wp-json/uaix/v1/validate"),
    message);

The typed send helper validates the UaiMessage locally before posting JSON. The lower-level string send method is still available when an application already owns serialization.

Validate And Switch .uaix Bundles

.uaix files are ZIP containers with a .uai/manifest.uaix.json manifest. UAIX.UAI can generate that manifest when exporting a normal folder, validates the newer manifest files array shape before extraction, and rejects unsafe entries such as path traversal, absolute paths, drive-root paths, device names, duplicate normalized paths, symlinks, manifest/file mismatches, and hash mismatches.

using UAIX.UAI.Core;

var exportResult = await new UaixPackageExporter().ExportDirectoryAsync(
    sourceDirectory: "profile-folder",
    destinationPackagePath: "profile.uaix",
    new UaixPackageExportOptions
    {
        PackageId = "creative-profile",
        ProfileId = "creative-profile",
        Issuer = "MyDesktopApp"
    });

if (!exportResult.IsValid)
{
    throw new InvalidOperationException(string.Join(Environment.NewLine, exportResult.Errors.Select(issue => issue.Message)));
}

var validator = new UaixPackageValidator();
var result = await validator.ValidatePackageAsync("profile.uaix");

if (!result.IsValid)
{
    throw new InvalidOperationException(string.Join(Environment.NewLine, result.Errors.Select(issue => issue.Message)));
}

var store = new UaixBundleStore("uaix-bundles");
var bundle = await store.ImportAsync("profile.uaix");
await store.ActivateAsync(bundle.PackageId);

Package validation and bundle activation do not mutate running AI instances. Running-instance communication should still use explicit UAI-1 message endpoints such as HttpUaiClient.

When a source folder does not already contain .uai/manifest.uaix.json, UaixPackageExporter generates the manifest, file hashes, declared scopes, entrypoints, support boundary, and manifest sentinel in the archive without mutating the source folder. Set RegenerateManifest = true when a source folder has a stale manifest that should be replaced during export.

Imports validate into a staging directory, then replace the target bundle content directory rather than merging into stale files. Exports must write the .uaix file outside the source directory so a package cannot accidentally include itself.

LocalEndpoint-Style Runtime Handoff

A desktop app can keep package storage and live instance communication separate. Import and activate the bundle locally, then attach the active bundle as declared context only when an explicit runtime send occurs:

using System.Text.Json;
using UAIX.UAI.Core;

var store = new UaixBundleStore("uaix-bundles");
var installed = await store.ImportAsync("creative-profile.uaix");
await store.ActivateAsync(installed.PackageId);

var activeBundle = await store.GetActiveAsync();
var bundleContext = activeBundle == null
    ? null
    : UaiRuntimeBundleContext.FromBundle(activeBundle);

var peer = new UaiRuntimePeer(
    new Participant("agent", "localendpoint-desktop"),
    new Uri("https://localhost:7443/uai"));

var message = UaiMessage.Create(
    "agent.request",
    new Participant("agent", "desktop-shell"),
    peer.Participant,
    JsonSerializer.SerializeToElement(new
    {
        task = "continue_with_active_bundle"
    }));

var channel = new UaiRuntimeChannel(new HttpUaiClient(httpClient));
var response = await channel.SendAsync(peer, message, bundleContext);

UaiRuntimeChannel copies the message before adding the uaix_active_bundle extension, so caller-owned messages remain unchanged. UaixBundleStore.ActivateAsync only changes local active-bundle state; it does not send, approve, apply, or synchronize runtime messages.

Placement decision: .uaix package support stays in UAIX.UAI.Core for the current package line so desktop apps can use package state and UAI messaging from one SDK. Split it into a dedicated package later only if the desktop integration surface grows enough to justify the extra dependency boundary.

Build

dotnet restore
dotnet build -c Release
dotnet pack -c Release

Packages are emitted to the UAIX publish pickup folder:

E:\Source\WP\UAIX-Publish\DOTNET-NUGET

Expected package files:

• UAIX.UAI.1.0.4.nupkg
• UAIX.UAI.Memory.1.0.4.nupkg
• UAIX.UAI.Abstractions.1.0.4.nupkg
• UAIX.UAI.Build.1.0.4.nupkg
• UAIX.Talisman.AgentClient.0.1.10.nupkg

Symbol packages are emitted as .snupkg files.