AgentC is an experimental runtime for agents that need more than prompt text, JSON tool calls, and short-lived scratchpads. It gives an agent a persistent memory graph, a compact native language ("Edict", for Executable Dictionary), rollback-safe execution, dynamic access to C/C++ capabilities, embedded logic programming, cognitive skill scaffolds, and local worker agents in one substrate.
Edict, AgentC's VM language, is the agent control plane. Provider sessions, tool use, context management, speculative branches, delegated worker agents, and cognitive state machines all live inside the VM. C++ remains the native layer for memory, persistence, credentials, transports, and unsafe system capabilities.
AgentC is currently an internal-alpha research prototype. It is useful for experimentation and for building early agent loops, but interfaces are still evolving.
Most agent systems serialize cognition through text and API calls. That works for simple tool use, but it becomes expensive when an agent needs durable state, branching reasoning, native capabilities, or local helper agents.
AgentC is designed for applications where an agent should be able to:
- Keep working memory alive across turns and process boundaries instead of reconstructing state from summaries.
- Try a branch and roll it back cheaply instead of reasoning only in prose about what might happen.
- Call native libraries as part of cognition instead of treating every capability as a separate JSON tool boundary.
- Use logic queries for bounded planning problems such as dependency resolution, migration ordering, or API-shape matching.
- Delegate narrow work to local worker agents without spending the primary model's context window on file reading, filtering, or summarization.
- Maintain structured cognitive state (hypotheses, evidence, findings) across turns using durable scaffold objects that serialize to JSON.
AgentC is not just another chat wrapper. It is a candidate operating environment for agents whose memory, actions, constraints, and provider state should live together.
AgentC stores state in arena-backed Listree nodes. Pointers are relative offsets, so state can
be persisted through file-backed slabs and restored without reconstructing an object graph.
Named sessions (edict --session ID) survive process restart through deterministic
root/scheduler/static-mount resume.
AgentC allocation is watermark-based. A checkpoint is one integer; rollback is resetting that
integer. The same primitive supports Edict speculate [...], transactions, and miniKanren
backtracking. Branch exploration becomes a runtime operation instead of an expensive text-only
habit.
Edict is a small concatenative language built for VM execution and LLM emission. It is compact, stack-oriented, and designed around explicit state effects. This makes it suitable for provider loops, tool orchestration, rollback probes, and generated helper code.
Cartographer imports C/C++ headers at runtime using libclang/libffi and reflects functions into AgentC memory. Imported functions become Edict-callable words. A structural diff engine, AST parser, solver, database binding, or specialized system library can become part of the agent's working environment.
miniKanren is embedded alongside Edict. Logic queries share the same memory substrate and use the same rollback mechanics. Constraint solving can be part of the agent's thought process, not an external microservice.
Reusable Edict-level state machines for investigation, code review, and refactor planning.
Scaffold state is ordinary Listree — it serializes with to_json!, survives across VM
executes, and can be snapshot/restored for branch isolation.
Overlay dictionaries let worker agents shadow specific keys on a frozen shared configuration
without mutating the coordinator's state. The frozen base stays ReadOnly; the worker's shadow
values are mutable and inspectable through overlay.commit!.
| Application | Why AgentC helps |
|---|---|
| Persistent coding agents | Durable scratch memory, provider state, and project facts survive context churn. |
| Refactoring planners | Speculative branches and logic constraints can model alternative edit plans. |
| Tool-rich local agents | Native libraries can be imported directly instead of wrapped by ad-hoc services. |
| Long-running research agents | Intermediate findings can live in structured memory, not only in transcript text. |
| Local intern agents | Secondary models can gather, filter, and summarize while the primary model decides. |
| Constraint-heavy automation | miniKanren can solve bounded dependency/order/matching problems explicitly. |
| Multi-branch reasoning | Speculative execution with slab rollback enables ToT/MCTS-style exploration (future). |
AgentC has four user-visible layers:
Agent / user intent
│
▼
Edict control plane
provider loops, tools, memory updates, speculation, logic calls,
cognitive scaffolds, overlay dictionaries, intern worker dispatch
│
▼
Persistent Listree state
one graph for objects, scopes, lists, runtime data, imported capabilities
│
▼
Native substrate
mmap/slabs, C/C++ FFI, provider transports, credentials, file/shell helpers,
Root1 eventfd/epoll broker, process-isolated workers
The important shift is that the agent is not just asking a host process to run tools. The agent can increasingly own the loop inside Edict: maintain provider state, mutate structured memory, call native code, probe branches, delegate to workers, and decide what to keep.
Prerequisites:
- C++17 compiler
- CMake 3.16+
libffi-devlibclang-devlibcurldevelopment package- POSIX-like environment with pthreads
Build:
cmake -B build
cmake --build build -j2List available LLM/provider presets through the curated launcher:
EDICT_AUTO_CHAT=0 ./edict.sh -e 'llm.catalog! to_json! print'Start the raw Edict REPL:
./build/edict/edictCreate or resume a named Edict session. Session images are stored under
/tmp/session/<id>/ by default; use --session-base or EDICT_SESSION_BASE to choose a
different root.
./build/edict/edict --session demo -e "'persisted @answer"
./build/edict/edict --session demo -e 'answer print'Start the curated AgentC launcher. With the default environment it enters the Edict-owned provider chat path:
./edict.shUse EDICT_AUTO_CHAT=0 when you want raw curated Edict execution instead of chat mode.
The current LLM surface centers on stable provider objects. A provider owns runtime config, conversation state, request thunks, streaming thunks, and tool references.
llm.init([gemma-4-31b-it]) @provider
provider < [Reply with exactly two lowercase letters: ok] request! > / /
provider.assistant_text print
The pattern provider < method! > / / enters provider scope, invokes the method in place,
leaves scope, and discards the returned context/sentinel values.
Provider-owned context can be managed from Edict. context_inspect! returns a summary;
context_reset! clears conversation history while preserving the provider object and system
prompt. Inside provider.repl(), the same behavior is available as /context and /reset
slash commands.
provider < context_inspect! > / @summary
summary.messages to_json! print
provider < context_reset! > / /
Live Google/Gemma requests use GEMINI_API_KEY or GOOGLE_API_KEY when present:
EDICT_AUTO_CHAT=0 ./edict.sh -e 'llm.init([gemma-4-31b-it]) @provider provider < [Reply with exactly two lowercase letters: ok] request! > / / provider.assistant_text print'speculate [...] runs code in an isolated checkpoint. Results can be inspected, but side
effects do not commit to the caller.
./build/edict/edict - <<'EDICT'
'baseline @answer
speculate ['candidate @answer answer] to_json! print
answer print
EDICTExpected output:
"candidate"
baseline
This example asks miniKanren for members of a list and serializes the result as JSON. Run it from the project root after building:
./build/edict/edict - <<'EDICT'
[./build/kanren/libkanren.so] [./cartographer/tests/kanren_runtime_ffi_poc.h] resolver.import! @logicffi
logicffi.agentc_logic_eval_ltv @logic
{
"fresh": ["q"],
"where": [["membero", "q", ["tea", "cake"]]],
"results": ["q"]
} logic! to_json! print
EDICTExpected output:
["tea","cake"]
Note: the interactive REPL compiles one line at a time. Use edict -, a script file, or -e
for multi-line object literals.
Cartographer can import a C header and shared library, then expose functions as Edict words:
./build/edict/edict - <<'EDICT'
'./build/cartographer/libagentmath_poc.so './cartographer/tests/libagentmath_poc.h resolver.import! @math
'3 '4 math.add! print
EDICTExpected output:
7
The current standard-library slice exposes JSON-envelope file and shell helpers. Provider
objects carry provider.tools, so tool calls can be scoped to the same provider-owned state.
llm.init([local-qwen]) @provider
provider < [/tmp/agentc-note.txt] [hello] tools.write_file! @last_tool > / /
provider < [/tmp/agentc-note.txt] tools.read_file! @last_tool > / /
provider.last_tool.content print
Investigation, code-review, and refactor-plan state machines with JSON-serializable state:
"parser-regression" cognitive.investigation_new! @investigation
investigation "H1" "cache-stale" cognitive.investigation_add_hypothesis! @investigation
investigation "H1" "edict/tests/vm_stack_tests.cpp:136" cognitive.investigation_add_evidence! @investigation
investigation to_json! @snapshot
snapshot print
Workers can shadow specific keys on a frozen shared configuration without mutating the coordinator's state:
{"model": "gpt-4", "temperature": "0.7"} @config
config freeze! @frozen_config
frozen_config overlay.new! @worker_view
worker_view "temperature" "0.2" overlay.set! @worker_view
worker_view "temperature" overlay.get! print
worker_view "model" overlay.get! print
frozen_config.temperature print
Expected output:
0.2
gpt-4
0.7
./build/demo/demo_composite_speculation_logic_ffiThis demo composes Cartographer-imported native FFI (add(10,32)=42), a miniKanren query
parameterized by the native result, and durable Listree state commitment in one deterministic
script.
AgentC is usable today as an experimental local runtime with these working surfaces:
- Edict compiler, VM, REPL, contexts, rewrite rules, transactions, and
speculate [...]. edict --session IDfor named session create/resume with deterministic root/scheduler/static-mount restore.- Persistent Listree/slab substrate with file-backed persistence and mmap-backed session resume.
- Cartographer FFI imports for C/C++ headers and shared libraries, with re-entrancy capability metadata.
- Embedded miniKanren runtime with Edict-callable query evaluation.
- Tree-sitter bridge:
treesitter.load!/parse!/list!/diff!for AST parsing and structural diffing. - Persistent knowledge graph:
kgraph.create!/add_node!/add_edge!/get_node!/query!/nodes!/edges!. - Cognitive skill scaffolds: investigation, code-review, and refactor-plan state machines with JSON serialization.
- Overlay dictionaries:
overlay.new!/set!/get!/has!/keys!/shadow_keys!/commit!for reference-scoped ReadOnly sharing. - Curated
edict.shlauncher and Edict modules undercpp-agent/edict/modules/. - Provider objects via
llm.init(...)for local OpenAI-compatible models, Google/Gemini/Gemma, and OpenAI Codex. - File/shell helper surface attached to provider objects.
- Streaming provider path using background native workers and main-thread synchronization.
- Intern worker substrate:
intern_run!(blocking),intern_start!/intern_sync!/intern_cancel!(async), with quality contracts and backpressure. - Process-isolated workers: thread, fork, and fork/exec backends with independently mounted static declaration images.
- Root1 eventfd/epoll resource broker with mailbox descriptors,
await!, and scheduler persistence. - Composite demos:
demo_composite_speculation_logic_ffi,demo_overlay_dictionary,demo_cognitive_core_validation.
Maturity notes:
- This is an alpha research system, not a stable packaged product.
- Examples are intended to run from a built checkout.
- Provider availability depends on credentials and local model/runtime configuration.
- Full validation baseline:
edict_tests198/198,reflect_tests55/55,listree_tests83/83,cartographer_tests52/52,cpp_agent_tests56/56,treesitter_tests28/28.
A major intended use case is local "intern" agents: smaller or local models that perform narrow work for a primary agent without consuming the primary model's context budget.
Good intern tasks are bounded and checkable:
| Task type | Example |
|---|---|
| Information gathering | Read several files and extract method signatures matching a pattern. |
| Failure triage | Run tests and classify failures by subsystem. |
| Search + filter | Find all callers of a function and discard irrelevant matches. |
| Compression | Summarize a large diff into semantic changes. |
| Context proxy | Hold a large context and answer factual questions about it. |
The landed substrate includes module-backed deterministic intern_run! plus async job dispatch.
Load worker.edict / intern.edict over the worker primitive import before using these words:
-- task envelope shape: task_id, program, input, context, optional imports
worker_task intern_run! @worker_result
worker_task intern_start! @job
job.job_id intern_sync! @status
job.job_id intern_cancel! @cancel_status
intern_run! freezes context and imports, snapshots input, launches a fresh worker
EdictVM with a private workspace, executes the bounded Edict program, joins the worker,
and returns a structured envelope. Workers can also run as forked or fork/exec processes with
independently mounted static declaration images (G107). Quality contracts enforce bounded task
schemas and result trust validators (G099). Overlay dictionaries provide reference-scoped
ReadOnly sharing so workers can shadow specific keys without mutating coordinator state (G093).
The target architecture:
- A coordinator VM owns the mutable root state.
- Shared context/import tables are marked read-only before dispatch; workers can use overlay dictionaries for per-key shadow values.
- Each worker gets a fresh EdictVM and private workspace (thread, fork, or fork/exec).
- Re-entrant native tools can be shared; stateful provider handles remain coordinator-owned.
- Workers return structured findings; the coordinator decides what to merge.
- Edict-resident agent loop consolidation (G078): provider/session/tool/context semantics.
- Intern worker concurrency MVP (G091): blocking/async dispatch, lifecycle/drop/abandon, cancellation.
- Reference-scoped ReadOnly sharing (G093): overlay dictionaries with 7 VM opcodes.
- Curated native cognitive libraries (G094): tree-sitter, structural diff, knowledge graph.
- Cognitive skill scaffolds (G095): investigation/code-review/refactor-plan state machines.
- Authoritative mmap session resume (G096): deterministic root/scheduler/static-mount restore.
- Composite speculation + logic + FFI demo (G097).
- Architectural vision work product (G098).
- Intern task quality contracts (G099): bounded schemas, dispatch rejection, result validators.
- Edict isolation contract hardening (G100).
- Direct Edict tool-emission path (G101).
- Session ID startup flag (G102).
- Static declaration image MVP (G103), immutable code objects (G104), ReadOnly slab ownership (G105).
- Root1 slab advertisement registry (G106).
- Process-isolated micro-VM interns (G107): thread/fork/exec workers.
- Cursor-scoped traversal visit bitmaps (G108).
- Listree ReadOnly mutation surface hardening (G109).
- Root1 eventfd/epoll resource broker and micro-VM IPC design (G110).
- Root1/worker primitive FFI and Edict intern surface migration (G111).
- G075 — Speculative Edict Native Architectures (deferred): ToT/MCTS/ReAct-style multi-branch speculation using slab snapshot/rollback. The prerequisite control-plane stability and worker isolation are now in place. Activate when a concrete multi-branch reasoning demonstration is needed.
- Published result slabs: zero-copy immutable result sharing through Root1-advertised slab publications.
- Durable async job records: intern job state surviving process restart.
- Full activation-frame resurrection: kill-mid-op serialization and stable cross-version code-object identity.
- Shared-arena sidecar handoff: whole-VM/root restore across processes.
- Cartographer as general capability service: mature sidecar protocol and full binary introspection.
- Better user-facing examples and notebook-style executable docs.
- A tighter application-facing API around Edict-owned provider/session/tool loops.
Most users will start with edict.sh, cpp-agent/edict/modules/, and the examples above.
edict/ Edict compiler, VM, REPL, and tests
cpp-agent/ Provider runtime, persistence helpers, and Edict agent modules
cartographer/ Runtime C/C++ header import and FFI machinery
kanren/ Embedded miniKanren runtime
extensions/ File/shell/helper libraries importable from Edict
listree/ Persistent tree/list/value substrate
treesitter/ Tree-sitter grammar and bridge for AST parsing/diffing
demo/ Demonstrations and shell smoke tests
LocalContext/ Project memory, design notes, goals, and current status
LocalContext/Dashboard.md— current project state and latest validation baselineLocalContext/Knowledge/WorkProducts/edict_language_reference.md— detailed Edict language referenceLocalContext/Knowledge/WorkProducts/WP-LlmsGuideToEdictVm-2026-05-10/index.md— LLM-oriented Edict/VM guideLocalContext/Knowledge/WorkProducts/WP-AgentCArchitecturalVisionInternConcurrency-2026-06-21.md— architectural vision and intern concurrency model