KeyLoad

One database for AI agents.

KeyLoad brings documents, typed tables, graphs, blobs, queues, events, vectors/search and time series into one database. Models share canonical entity references: a task can point to a document, that document can be part of a knowledge graph, and its files, history and search results stay connected.

SQL is the familiar shared language for combining these models. Agents and applications connect through the .NET SDK, the integrated official MCP server, or the HTTP and simple agent APIs.

Website · Documentation · Architecture

What you can build

• Agent memory and retrieval: keep source documents, files, embeddings and relationships together for contextual search.
• Knowledge graphs: connect documents and typed rows, traverse their relationships, and turn discoveries into tasks.
• Reliable agent workflows: schedule work, lease tasks, retry failures and record processing results alongside database changes.
• Event-driven applications: retain event history, follow changes and maintain projections.
• Time-series analysis: store timestamped samples and read ranges, aggregates and time windows.

Data model	Purpose
Documents and typed tables	JSON records, schema-constrained rows, indexes and revision-checked updates
Graphs	Relationships between entities and bounded traversal
Vectors and text search	Exact vector retrieval, lexical search and combined ranking
Files and blobs	Chunked uploads and partial reads
Queues	Scheduled work, leases, retries and dead-letter handling
Events and topics	Ordered history, durable subscriptions and checkpoints
Time series	Timestamped samples, range reads and aggregation

One database, connected models

Collections, tables and queues organize data within the same database. An agent can follow references across models while the database checks its permissions.

• Queue to knowledge graph. QueueToGraph reads ready messages, resolves their linked entities and writes knowledge-graph relationships.
• Graph to queued actions. GraphToQueueMutation follows visible graph relationships to enqueue actions referencing those entities.

The current composition API submits these operations through .NET CommitAsync, SQL CALL keyload_documents_commit(@arguments) or official MCP. Resources must share the same atomic partition and transaction domain; the batch succeeds or rolls back together. Queue-to-graph projection does not lease or ACK messages. Blobs remain part of the same database, with separate upload and publication operations.

See the composition guide and its transaction contract for limits, permissions and retries.

Development status

KeyLoad is a development preview. The current SQL subset provides bounded document queries and calls to database operations. Full declarative SQL, the native SQL-client protocol and cross-partition composition are still in development.

The default server is a three-node replicated cluster (RF3), built on Orleans with persistent ZoneTree storage on each node. Production readiness, endurance, power-loss durability and comparative performance remain under qualification. The implementation tracker, SQL compatibility inventory and test results record the detailed status.

The server uses ZoneTree.FullTextSearch for bounded derived text candidates while preserving exact authorized ranking. Search now awaits complete native execution and cleanup while retaining its analytical reservation. The development receipt records full Aspire normal/scalar suites at 2,866 tests each and recovery at 228, including the new native admission/cancellation cases and 10 native-text process cuts. Exact-source Linux/RF3 qualification and incremental projection replay remain pending; these checks establish no speed improvement.

A bounded lossless time-series chunk codec has development evidence from full Aspire unit/scalar suites and matched native-codec controls. Canonical chunk storage, rewrite/recovery and RF3 qualification remain in progress under KL-078.

Get started

Install the .NET SDK selected in global.json and Docker, then build from the repository root:

dotnet restore KeyLoad.slnx
dotnet build KeyLoad.slnx --no-restore --configuration Release

To run the RF3 cluster, configure KeyLoad__ContainerImages__Server with a source-built server image in registry/image:tag@sha256:<digest> form, then start the Aspire AppHost:

dotnet run --project src/KeyLoad.AppHost --configuration Release --no-build

Aspire starts three Docker nodes at http://localhost:5101, http://localhost:5102 and http://localhost:5103. Node data and the private development credentials live under data/cluster/; keep them across restarts. Container configuration is described in the Docker setup.

Open http://localhost:5101/admin for the administration console, or check the cluster with the CLI:

dotnet run --project src/KeyLoad.Cli --configuration Release --no-build -- \
  status http://localhost:5101 data/cluster/local-profile.json

Use the .NET SDK

The client SDK exposes typed database operations. This example creates a collection and writes an order using an API key with the required permissions. Set KEYLOAD_API_KEY in your application environment; the local development key is stored in data/cluster/local-profile.json as AdminKey.

using KeyLoad;
using KeyLoad.Client;

var apiKey = Environment.GetEnvironmentVariable("KEYLOAD_API_KEY")
    ?? throw new InvalidOperationException("Set KEYLOAD_API_KEY.");
using var http = new HttpClient { BaseAddress = new Uri("http://localhost:5101") };
var client = new KeyLoadClient(http, apiKey);
var partition = new PartitionRef("acme", "shop", "orders", "customer-42");

var collection = await client.ConfigureResourceAsync(Guid.NewGuid(), new("acme", "shop",
    new ResourceDefinition("orders", ResourceKind.Collection, "orders")));
collection.ThrowIfFail();

var commandId = Guid.NewGuid(); // Keep this ID when retrying the same write.
var result = await client.CommitAsync(new CommandRequest(commandId, partition,
[
    new PutDocument("orders", "order-1", "{\"status\":\"new\"}", ExpectedRevision: 0)
]));
result.ThrowIfFail();

var order = await client.GetAsync(new EntityRef(partition, "orders", "order-1"));
order.ThrowIfFail();

For agent integrations, the MCP and API guide describes the shared operation catalog. The query guide covers supported SQL and query limits; the documentation index links the remaining database APIs.

Credits

KeyLoad is developed by Managed Code and builds on these projects. Thank you to their authors and contributors.

Project	How KeyLoad uses it
.NET and ASP.NET Core	Server, client SDK and HTTP hosting
Orleans	Distributed request execution, cluster routing and binary serialization
ZoneTree	Persistent ordered storage for the database models
MCP C# SDK	Integrated MCP server and real MCP clients
ManagedCode.Communication	Typed operation results and ASP.NET Core/Orleans integration
ManagedCode.Storage	File-system storage and backup transfer support
ManagedCode.TimeSeries	Time-series aggregation
ManagedCode.Orleans.Graph	Grain call relationship policies
Cartograph	Segmented backup archives and catalogs
OpenTelemetry .NET	Logs, metrics and traces

Development and presentation also use Aspire for Docker orchestration, TUnit for tests, BenchmarkDotNet for microbenchmarks, and Three.js for the website's cluster illustration.

License

KeyLoad is licensed under MIT.

Developed by Managed Code.