Skip to content

A minimal .NET client for the memory ops: set, get, search and delete - #1012

Open
hskl18 wants to merge 1 commit into
ClickHouse:mainfrom
hskl18:feat/621-dotnet-memory-client
Open

hskl18 wants to merge 1 commit into
ClickHouse:mainfrom
hskl18:feat/621-dotnet-memory-client

Conversation

@hskl18

@hskl18 hskl18 commented Nov 20, 2026

Copy link
Copy Markdown
Contributor

Closes: #621
Related: #54

Changelog category (leave one):

  • New Feature

Changelog entry (one or two sentences a user of Loom can read without the diff; the release pull request collects these into the release notes):

A minimal .NET client (sdk/dotnet, .NET 8) saves, reads, searches and deletes memories, and turns Loom's error envelope into a LoomException you can match on Code.

Why

.NET callers hand-roll POST /v1/<op> today. This is the first step #621 describes, which the full .NET SDK in #54 can grow from. It follows sdk/java.

Scope and risk

New folder sdk/dotnet (a library, its xUnit tests and a solution), plus a .NET link in the README's SDK row and a .NET SDK row in docs/development/testing.md, as the Go client added.

  • LoomClient: built from LoomClientOptions (BaseUrl, optional Token, Org, Namespace, Agent, Timeout), or from LoomClient.FromEnvironment(org, ns, agent) reading LOOM_BASE_URL and LOOM_API_KEY. SetAsync, GetAsync, SearchAsync and DeleteAsync, each with an optional dictionary of the op's other inputs and a CancellationToken. Headers as sdk/java sends them: Authorization: Bearer only with a token, Content-Type, Accept, User-Agent: loom-dotnet/0.1.0, X-Request-Id.
  • Results: records for the fields a caller reads (MemoryId, Version, Value, Found, the search hits); each keeps the whole response as Raw.
  • LoomException: Code, Category, Retryable, RetryAfterSeconds (body retry_after_s, else the Retry-After header), the HTTP Status, the RequestId and the Op. A body that names no category or retryable falls back to the status, as docs/reference/errors.md describes. A call that got no answer has status 0 and is a retryable dependency error, UNREACHABLE or TIMEOUT. Cancelling through the caller's own token stays an OperationCanceledException.
  • Redirects: the HttpClient the client creates does not follow them, so a 3xx throws instead of sending the memory write on to another address, the fix the Go client got in review. An HttpClient passed to the constructor keeps its own settings; .NET's default handler follows a 307 and resends the body, which the README says.
  • The client-owned HttpClient has a 10 s connect timeout, as sdk/java sets, and no request timeout of its own; each call ends at Timeout (30 s by default) through a linked cancellation token, so a Timeout above 100 s works.
  • Dependencies: none beyond .NET 8 (HttpClient, System.Text.Json). Tests: xUnit 2.9.3, xunit.runner.visualstudio 3.1.5, Microsoft.NET.Test.Sdk 18.12.0. Built with warnings as errors.

Compatibility, rollout and rollback

  • Wire: none; the client calls existing ops.
  • Operator steps: none.
  • Rollback: reverting removes sdk/dotnet and the two doc rows.

Tests

Unit tests (29) with a stubbed HttpMessageHandler, and local sockets where the real handler matters (an unreachable port, a 307 to a second listener, FromEnvironment over HTTP/1.1): the path and body of each of the four calls, the request headers on set and get, the typed results, one error answer per category, NOT_FOUND matched by code, nine status fallbacks for a body without an envelope, the timeout, the caller's cancellation, and the required options. cd sdk/dotnet && dotnet test on .NET SDK 8.0.428, Linux:

Passed!  - Failed:     0, Passed:    29, Skipped:     0, Total:    29

I made 16 single breaks (such as following redirects, a misspelled top_k, no status fallback, no per-call deadline), one at a time, and each made the suite fail.

By hand against a local Loom: ClickHouse 26.10 with the repo's deploy/clickhouse-config, migrations, uvicorn server.main:app as make server runs it, single-user. The README example ran unchanged, then a check of each answer and a search with top_k=-1 for the error mapping:

Prefers an aisle seat on long flights.
seat_pref
set    -> memory_id=fffc4414-02d9-4c2e-b148-207fd0052fdf version=1795140961977843529 status=active
get    -> found=True value=Prefers an aisle seat on long flights. version=1795140961977843529
search -> seat_pref (0.163)
delete -> tombstoned=True found=True version=1795140962393489752
get after delete -> found=False
bad input -> status=422 code=VALIDATION_FAILED category=input retryable=False

Repository checks: make format-check, make lint and make typecheck pass; test_public_copy.py and test_doc_links.py pass. Of make test-unit, pytest bench -q passes (251), and pytest tests/unit -n 16 has 45,140 passed and 3 failed, none in code this PR touches. test_code_lang_lua.py's linear-time case passes when run alone. The two test_cross_replica_auth.py retire tests fail the same way on the base commit here (retiring 'k1' would leave no key to sign with).

CI wiring for .NET is out of scope, as the issue says.

AI assistance in the code (leave one; writing this description with AI is fine):

  • AI-generated (an agent wrote most of the diff): Claude Code wrote the client, tests and README, and Codex reviewed the diff. I checked the request bodies and error mapping against sdk/java and docs/reference/errors.md, ran the tests, made 16 single breaks one at a time and saw each fail the suite, and ran the README example against a local Loom.

  • I can explain every line of this diff and how it interacts with the rest of Loom.

Checklist

  • make format-check, make lint, make typecheck and make test-unit pass; the integration suite passes if server behaviour changed. (make format-check, make lint and make typecheck pass; make test-unit does not: pytest bench passes and pytest tests/unit has three failures outside this PR, listed under Tests.)
  • Docs under docs/ describe the system as it now is, and this description names any operator steps and wire changes.
  • Repository text has no dates, people, host names, internal namespaces, ticket or decision numbers; the history goes in this description (tests/unit/test_public_copy.py).
  • Commits are signed off (git commit -s), as CONTRIBUTING.md asks.

… memory.delete

.NET code that wants agent memory hand-rolls POST /v1/<op> today. A small
hand-written client in sdk/dotnet, shaped like sdk/java, gives it the four
memory calls and turns the error envelope into a LoomException it can match
on Code, and is a tested starting point for a full SDK.

The HttpClient the client creates does not follow redirects: a followed 307
or 308 would send the memory's value to wherever the answer points.

Signed-off-by: hskl18 <thb182003@gmail.com>
@zlareb1 zlareb1 self-assigned this Nov 20, 2026

@zlareb1 zlareb1 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

No blocking findings. Checked all four request and result contracts, error categories and retry hints, cancellation and deadlines, response ownership and redirect refusal against the wire reference. The 29 .NET tests pass in Linux with warnings as errors, and all 271 documentation checks pass.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

A minimal .NET (C#) client for the memory ops: set, get, search and delete

2 participants