Nucleoid: a declarative logic runtime that keeps assignments true

The problem Nucleoid targets: implicit knowledge in LLM weights

The README states the motivating problem directly: hallucinations are a major challenge in LLM reasoning because natural language is unstructured, and LLMs are pattern engines that reason more effectively over structured entities and relationships. The project's answer is to move the domain model out of the weights and into an executable structure. A world model, as the README defines it, is what a system knows about a domain: which entities exist, how they relate, which rules hold across all of them, and what follows once something changes. In an LLM that model is implicit and spread across the weights. Nucleoid's position is that a model which cannot be inspected cannot be corrected and cannot be held to its own rules. The audience is therefore narrow and specific: engineers building neuro-symbolic systems who want a symbolic layer that an LLM can emit and a runtime can check, rather than a general application language. The README also frames this as an extension of the knowledge graph, with the distinguishing feature being that the graph is executable rather than merely stored.

Assignments as maintained relationships, not one-shot instructions

The mechanism that separates Nucleoid from a conventional language is stated plainly in the reference: a Nucleoid program is a set of statements that remain true, and an assignment is not an instruction that runs once and finishes, it is a relationship the runtime records and maintains. The README's example makes the consequence concrete. Given a = 1 and b = a + 2, then a = 3, the assertion assert(b, 5) holds. The value of b is never stale because b is defined as the sum of a and 2, so rebinding a propagates. The same rule is documented as applying to properties, class-level rules, and everything else the reference covers. This is a dependency graph with automatic invalidation, and it is the reason the language can be described as declarative without being a query language. The Hello World example shows the inference side: a class Human(name: str) is declared, a class-level rule $Human.mortal = true is attached, socrates = Human("Socrates") creates an instance, and assert(socrates.mortal, true) passes. Nothing in the program states that Socrates is mortal. The runtime derives it from the class rule and the instance membership. The README calls the result near-deterministic, and the hedge is honest: the reasoning is deterministic, but the LLM that writes the statements is not.

Two runtimes, one specification, and a normative document

The repository table splits the project in two. On one side is the Rust-based programming language runtime in this repo, which the README describes as implementing the language specification by executing declarative statements. On the other side is a fine-tuned LLM hosted at huggingface.co/nucleoid, described as fine-tuned on synthesized datasets derived from the language specification. The pairing is the neuro-symbolic claim in concrete form: the LLM produces .nuc statements, the runtime executes them and maintains the relationships. Documentation is assembled from NUC documents in docs/, indexed by NUC 0 with conventions in NUC 1, and docs/README.md is the language reference covering statements and state, variables and dependencies, expressions, types and instances, properties, class-level rules, blocks and scope, control flow, functions, transactions, built-in objects, error messages, and a syntax summary. One governance detail matters more than it looks: nucleoid.spec.md is normative, and where the reference and the specification disagree, the specification wins. That is a sensible rule, but it means the prose reference is explicitly secondary, so anyone reading only docs/README.md is reading a document the project has already declared may be wrong.

Getting it running and what the example suite actually proves

The README gives two verifiable entry points rather than a quickstart. First, docs/examples.md covers the same ground as the language reference in the form of complete programs, each one runnable as written. Second, and more useful, tests/reference.md is described as the executable form of the reference and runs under cargo test, as do the snippets on the README page itself. That is the strongest claim in the material, because it is falsifiable: clone the repository, check out the rust default branch, and run cargo test. If the reference suite passes, the documented semantics are exercised by the suite rather than asserted in prose. The syntax itself is small. A class is declared with class Human(name: str):, the body assigns this.name = name, a class-level rule is prefixed with $, an instance is constructed by calling the class, and assertions use assert(actual, expected). The README describes the syntax as minimally tokenized and declarative, and the design intent is that an LLM does not have to manage control flow or state propagation. That is a real constraint on the grammar, not a marketing line: every imperative construct an LLM would have to emit correctly is a token it can get wrong. Distribution is the one place the material is ambiguous. The README links an npm package named nucleoidai, while the repository is a Rust project on a branch named rust. The material does not state which crate or binary you install to get the Rust runtime, so that is the first thing to confirm before planning an integration.

Where Nucleoid is the wrong tool

The declarative model has a cost that the README does not discuss. If b is maintained as a function of a, then every write to a triggers recomputation of everything downstream. The material describes the maintenance behavior but gives no information about how the runtime schedules or bounds that work, so anyone considering a domain with large fan-out dependencies is choosing without data. The release history is the second constraint. The most recent release listed is v0.7.10 from June 2024, and the last push to the repository is dated August 2026, which suggests active development between releases rather than a frozen project, but the version number is still 0.x and the language reference is assembled from numbered NUC documents, a format that usually signals a specification still in motion. Third, this is not a database. There is no mention of persistence, durability, transactions across processes, or a query planner in the supplied material, although the reference does list transactions as a covered topic. If your requirement is a durable store with an optimizer, Nucleoid is a reasoning layer and you will need something else underneath it. Finally, the neuro-symbolic framing depends on the fine-tuned model at huggingface.co/nucleoid. The material does not state how that model is evaluated, what it was trained on beyond the phrase synthesized datasets derived from the language specification, or how often it emits statements the runtime rejects. Without that, the reliability of the LLM half of the loop is unverified.

How this differs from Prolog and Datalog

The nearest comparison is a logic language like Prolog or Datalog, and the difference is in what triggers evaluation. In Prolog you pose a query and the engine searches for a derivation; the program is a set of rules and the work happens when you ask. In Datalog you compute a fixpoint over a set of facts and rules, typically in a batch. Nucleoid inverts the direction: you write assignments that hold, and the runtime keeps them holding as inputs change. The README's a = 1, b = a + 2, a = 3, assert(b, 5) sequence is not a query against a static database, it is a propagation triggered by a rebinding. That makes Nucleoid closer to a reactive constraint layer than to a query engine, and it is why the README describes the result as an executable knowledge graph rather than a knowledge base. The practical difference shows up in how you integrate with an LLM. With Prolog you would have the model emit rules and then issue queries and interpret the answers. With Nucleoid the model emits statements and the runtime maintains state, so the model does not need to track what changed. Whether that trade is worth it depends on whether your domain is dominated by inference over a fixed set of facts (Datalog's strength) or by state that changes and must stay consistent (Nucleoid's target).

Licence, maintenance, and what upgrading involves

Nucleoid is Apache-2.0, which permits commercial use, modification, and redistribution provided you keep the licence and notice files and state significant changes. Apache-2.0 also includes an express patent grant, which matters if you are embedding this in a product. This is a description of the licence text, not legal advice; if you are redistributing a modified runtime, have counsel read the NOTICE requirements rather than relying on a summary. On maintenance, the material supports only a limited reading. Releases v0.7.8 through v0.7.10 landed within four days in June 2024, which indicates bursty rather than steady release cadence, and the last push date is well after the last tagged release, so commits are happening without version bumps. Because the specification is normative and lives in the repository as nucleoid.spec.md, an upgrade can change language semantics and not just the runtime binary, which means a version bump is a potential source-level change to your .nuc programs. The mitigation is available in the repository: tests/reference.md is the executable form of the reference, so running cargo test after any pull tells you whether the semantics you depend on still behave as documented. Budget for reading the diff on nucleoid.spec.md and docs/ before each upgrade, not just for rebuilding.

Editorial conclusion

Adopt Nucleoid if you are building a neuro-symbolic system where an LLM needs a small, inspectable rule layer over entities and relations, and you are willing to write .nuc statements rather than call a graph API. Do not adopt it if you need a mature query planner, a stable language spec, or a runtime you can debug from source without reading Rust. Before committing, verify three things: that the docs/README.md language reference and nucleoid.spec.md agree on the statements you intend to use, that cargo test passes on your toolchain so the reference examples in tests/reference.md actually execute, and which Rust crate the runtime is published under, since the repository layout and the npm package nucleoidai point at different distribution paths.

Official sources

1. License: Apache-2.0
2. NucleoidAI/Nucleoid on GitHub
3. Project website
4. README
5. Releases