.NET 10 host · Apache 2.0

Agents are actors.

Agctor is an open-source framework for agentic systems. Each agent owns its state, reads one message at a time, and talks only through envelopes. The host adds a dashboard, scene memory, a code graph, and retrieval — on the same contracts.

Run the host View the repository

.NET 10 and .NET 8
In-memory runtime
Scene Memory
CodeGraph

mailbox one message at a time

to: root-agent
reply-to: host
correlation: 4c91e2
payload: Maya enters the kitchen…

Actors never share memory. Results travel back on the same envelopes.

01

.NET 10 host

The host targets net10.0. Libraries, the CLI, the Orleans silo, and demos still build for .NET 8 and .NET 10.

02

Dashboard

Agents, scenarios, goals, tools, runtime, project memory, and RAG live on one host at port 5274.

03

Scene Memory

Prompts become a preview of characters, objects, and places. You review the diff, then apply. Shots line up on a timeline.

04

Code graph

A solution is an actor tree — project, file, class, method — with index, search, and review beside project memory.

01 — Model

One idea, then the rest follows.

If you remember only this: an Agctor agent is an actor. LLMs, tools, and story state are added without giving them a shared workflow object.

Own the state

Nothing reaches in

Each actor keeps its own state. Callers send a message. They do not mutate a graph they do not own.

One mailbox

No lock around a turn

Messages are processed one at a time. Timeouts are a supervisor actor, with progress and partial results, not a thread abort.

Envelopes

Routing lives on the message

Correlation, reply-to, and expiry belong to the envelope. Host, CLI, and MCP all enter through that shape.

Swap the runtime

Contracts stay put

Agents talk to IActorRuntimeAdapter. In-memory is the runtime you actually run. Proto.Actor and Orleans are experimental adapters.

02 — Platform

A host you can look at.

The same process serves the dashboard, REST, Swagger, and a loopback MCP listener. These panels illustrate that surface. They are not a live host.

localhost:5274Dashboard

Agents InMemory

cli-rootcompleted
llm · mistralreading
tool · editoridle
scene-queryready

CodeGraphactor tree

Solution
AgctorSDK.Host
Controllers
SceneMemoryController.cs

Search where is the mug

Index, semantic search, and review sit on the tree. Embeddings come from Ollama when you ask for them.

IActorRuntimeAdapterpick one

In-memory Proto.Actor Orleans

Ready · default

The host and CLI start here. Spawn, send, and request/response stay in process. This is the fully implemented runtime.

Experimental

A partial Proto.Actor adapter. It stays off until Agctor:AllowExperimentalRuntimes=true. The adapter version is still marked as a placeholder.

Experimental

The adapter connects to the Orleans silo, then runs agents on an in-process mailbox until grains cover every agent type. Same experimental flag as Proto.Actor.

Retrieval

RAG and project memory

Project memory keeps knowledge, a pipeline, and a playground. Retrieval providers are separate from scene memory. File memory is markdown retrieval. Scene memory cannot replace the default document provider.

Scenarios

Multi-step work

Scenarios coordinate longer runs from the dashboard, with decision routing and a model chosen for that scope. Goals break work into tasks the runtime can track.

Tools

Actors with side effects

C# and Python execution, filesystem, and a code editor. Compile, format, and test runners sit beside them. They run in-process, with no sandbox.

03 — Scene Memory

Story state, kept as facts.

Describe what happens. The model proposes characters, objects, and places, reuses identities it already has, and returns a preview. Apply writes that preview. Queries then answer from the stored facts — not from a guess.

Discovery Follow-up Ambiguous

Describe what happens

Maya enters the kitchen carrying a red mug. She places it on the counter.

Scene · Kitchen Shot · Entering

What will change

MayaCharacter

located_atKitchen

Red mugObject

colorred
onCounter
held_bycleared

KitchenPlace

statusdiscovered

CounterPlace

statusdiscovered

Follow-up · current facts included

Jordan picks up the red mug.

Scene · Kitchen Shot · The handoff

What will change

JordanCharacter

statusdiscovered

Red mugObject

held_byJordan
oncleared
colorred

MayaCharacter

located_atKitchen

Needs another preview

She puts it away.

Unresolved No write

Clarification required

Who is “she”, and what is “it”? Ambiguities are reported. Editing a row cannot dismiss them. Clarify the prompt and preview again. Unknown, expired, or stale previews conflict, with no partial write.

Illustration of the preview. The host calculates the real diff from the selected Ollama model. The three paths match the dashboard examples: discovery, a later transfer, and an ambiguous reference.

Timeline

Shots, then scenes

Applied prompts are shots. Consecutive shots with the same scene name group into a scene. Names and a planned duration can change without rewriting state or order.

Evaluation

100 cases, saved work untouched

Benchmark one to three installed chat models. The catalog covers possession, ownership, transfer, lifecycle, people, locations, condition, and intent. The report has pass rate, latency, host memory, and failure categories. The run is process-local. The JSON download is the record you keep.

Query

Facts, not a guess

Ask “Where is the mug?” from the page or from SceneMemoryQueryTool. Matching is the entity name or its id. An optional change number reads an earlier state. A studio API at /api/scene-memory/v1 connects an external story without taking an Agctor assembly dependency.

04 — Stack

Host on top. Runtime underneath.

Your code stays on the contracts. Change how actors run without rewriting how they think. Select a layer.

Host / CLIdoors in Agentsmailboxes CodeGraphrepo tree Toolsside effects Corecontracts Runtimeadapter

Consumer

Three ways a prompt arrives

HTTP at http://localhost:5274, Swagger at /swagger, MCP on 127.0.0.1:8080, or one CLI argument. The host redirects / to /Dashboard.

Intelligence

LLM, human, coder, memory

An LLM actor talks to local Ollama. A human adapter keeps a person in the loop. A coder agent runs edit, compile, and test. Session and project-memory agents orchestrate longer work. Default chat model: mistral.

Code intelligence

Solution down to method

Indexer, search, query, refactor, and review agents use the graph. Analyzers prefer Roslyn for C#, with an LLM fallback. Snapshots can be saved and diffed.

Tool layer

Each capability has a mailbox

Editor, executor, filesystem, compile, format, and test runner. Code execution is in-process. Use Agctor where you already trust the operator.

Foundation

No project references

IActor, IAgent, message envelopes, goals, scene-memory store contracts, and OpenTelemetry metrics and tracing. Implementations of the runtime live in Agents, not here.

Adapter

In-memory unless you opt in

Proto.Actor and Orleans register as experimental. Orleans currently delegates agent execution to the in-memory mailbox after the silo client connects. Application code does not bind to a backend.

05 — Start

Clone, build, pick a door.

Install the .NET 10 SDK. global.json asks for 10.0.100 and rolls forward in that feature band. Keep the .NET 8 runtime if you run net8.0. Ollama is optional until a live model is required.

01 · Clone

Get the source

github.com/rahamohebbi/Agctor

02 · Build

Every targeted framework

dotnet build Agctor.sln restores and builds net10.0 and net8.0 where a project multi-targets.

03 · Run

Host, CLI, or library

The host is the dashboard. The CLI is one prompt. Libraries drop into an existing app.

Dashboard, REST, Swagger, and a loopback MCP listener.

dotnet run --project AgctorSDK.Host
# Dashboard     http://localhost:5274
# Scene Memory  http://localhost:5274/Dashboard/SceneMemory
# Timeline      http://localhost:5274/Dashboard/SceneMemoryTimeline
# Evaluation    http://localhost:5274/Dashboard/SceneMemoryEvaluation
# Swagger       http://localhost:5274/swagger
# MCP           127.0.0.1:8080

There is no authentication yet. Read SECURITY.md before exposing the host. MCP binds to loopback by default.

One process, one prompt, one root agent. Useful as a script and as a smoke test.

dotnet run --project AgctorCLI --framework net10.0 -- "Summarize the actor model in one sentence"
# .NET 8:  --framework net8.0
# Runtime: optional second argument, default InMemory

Proto.Actor and Orleans need Agctor:AllowExperimentalRuntimes=true. Without that flag the CLI reports the runtime as unavailable.

Reference the packable projects. The default runtime is in-memory. Scene memory is a separate registration.

using AgctorSDK.Core.DependencyInjection;
using AgctorSDK.Extensions.DependencyInjection;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();
services.AddAgctor(); // in-memory runtime by default
services.AddAgctorSceneMemory("data/scene-memory.db");

Packable projects: Core, Agents, Tools, Extensions. Set Agctor__SceneMemory__StorePath to a durable absolute path when you deploy. Keep LICENSE and NOTICE when you redistribute.

06 — Repository

Know where new code goes.

The layout is the architecture. Core stays contracts. Agents, tools, host, and CLI stay in their projects. Product requirements stay in Project/, not in source.

contracts

AgctorSDK.Core

Actors, envelopes, goals, scene-memory contracts, timeouts, observability.

actors

AgctorSDK.Agents

Agent actors and the runtime adapters: in-memory, Proto.Actor, Orleans.

tools

AgctorSDK.Tools

Code, files, editor, compile, format, test, and scene-memory query.

graph

AgctorSDK.CodeGraph

Codebase graph, indexing, search, and review agents.

di

AgctorSDK.Extensions

AddAgctor(), scene memory, and runtime adapter wiring.

gateway

AgctorSDK.Host

Dashboard, REST, Swagger, MCP. Integration tests target .NET 10.

entry

AgctorCLI

Single-prompt runner. It boots CodeGraph with the same SDK stack as the host.

cluster

Orleans silo

AgctorSDK.OrleansSilo and AgctorSDK.Orleans.Contracts. The Docker image defaults to .NET 10.

Open source

Apache 2.0. Come build on it.

Keep copyright notices and the NOTICE file. Cite the project with CITATION.cff if you use it in a paper or product. Code-execution tools run in-process with no sandbox — run Agctor in environments you trust.

Open the repository Contributing guide Scene Memory API