Home / MeTTa Programming Language / Hyperon Experimental / Hyperon Experimental Full
Hyperon Experimental is the official trueagi-io Rust reference implementation of the MeTTa runtime. At HEAD 3f76dc46 (v0.2.10, 2026-02-11), it is the foundational MeTTa runtime substrate that all alternative MeTTa runtimes either port, transpile, embed, or bridge.
3f76dc460da6961f57f69f6c3e550c59c74ada83hyperon-common, hyperon-atom, hyperon-space, hyperon-macros, lib, c, replpython/ (pybind11 bindings + sandbox), integration_tests/das/, docs/[SMALL-STEP-INTERPRETER] [NONDETERMINISTIC-BRANCHING]
Stack-based, plan/state-driven, nondeterministic. NOT a deterministic "first match wins" rewrite engine — multiple matches produce multiple results. Key entry points in lib/src/metta/interpreter.rs:
interpret_step (L269) — main reduction stepinterpret_stack (L374) — stack dispatch with depth enforcement (L392)eval_impl (L504), eval_result (L559), query (L604)chain (L687), collapse-bind (L746), unify (L809), superpose-bind (L893)Boundary: programs requiring deterministic dispatch must use mutually exclusive patterns. Catchall equations ($_, $other) alongside specific equations produce multiple reductions — this is documented language semantics, not a defect.
[DYNAMIC-CHECKED]
lib/src/metta/types.rs:
%Undefined% is permissive wildcard — assigned to atoms without a user type, matches any required type (L18-19)check_arg_types (L65), get_atom_types (L327), get_application_types (L512), UndefinedTypeMatch (L526)check_type (L602), validate_atom (L637)Hyperon Experimental supports expressive type checking, but should NOT be described as a fully-settled categorical/dependent-type verifier.
[HYBRID-RUST-PLUS-METTA-STDLIB]
Split between Rust-side token registrations under lib/src/metta/runner/stdlib/ and MeTTa-side definitions in stdlib.metta (1,421 lines). Cross-runtime audits must cover both layers.
Rust-side modules:
arithmetics.rs (L162-198): +, -, *, /, %, <, >, <=, >=, and, or, not, xor, divisionatom.rs (L449-474): unique-atom, union-atom, intersection-atom, max-atom, min-atom, size-atom, index-atom, subtraction-atom, get-type, get-metatype, get-type-spacecore.rs (L336-362): pragma!, nop, sealed, ==, match, if-equal, superpose, capture, _minimal-foldl-atomdebug.rs (L155-177): trace!, print-alternatives!, =alphamath.rs (L408-443): pow-math, sqrt-math, abs-math, log-math, etc., plus PI and EXP constantsmodule.rs (L280-298): import! (L290), include, mod-space!, print-mods!, bind! (L269), module-space-no-depspackage.rs (L113-117): register-module!, git-module!space.rs (L206-223): new-space, get-state, change-state!, get-atoms, add-atom, remove-atomMeTTa-side definitions in stdlib.metta: return (L47), function (L54), eval (L61), chain (L78), unify (L88), cons-atom (L96), decons-atom (L103), collapse-bind (L239), superpose-bind (L246), metta (L255), switch (L345-362), if (L511-513), let/let* (L542-553), collapse (L1203), case (L1224-1233).
NOTE: there is NO replace-atom! MeTTa op at HEAD. PATCH-2 from the AtomSpace Integration Phase 4 cluster pilot recommends adding it.
[BUILTIN-FULLY-WIRED]
lib/src/metta/runner/builtin_mods/mod.rs registers six loaders:
random, skel, fileio, jsoncatalog (pkg_mgmt Cargo feature)das (das Cargo feature, default-enabled per lib/Cargo.toml:46)Each module pairs a .rs registration file with a .metta doc file (catalog.metta, das.metta, fileio.metta, json.metta, random.metta, skel.metta).
DAS is available as a default feature and builtin module surface, but does NOT mean a running distributed DAS service is embedded in the local runtime — metta-bus-client connects to a remote DAS service.
[MODULE-SYSTEM-PARTIAL]
Implemented and active but evolving (per docs/modules_internal_discussion.md's "poor man's" public/private scope concept).
lib/src/metta/runner/modules/mod.rs:
ModId (L27), MettaMod (L56), resource and loader fields (L58, L62)import_dependency_as (L107), import_item_from_dependency_as (L131), import_all_from_dependency (L181)ModuleLoader trait (L563), Resource (L608)mod_names.rs:265 and :276Imports via import! (registered at stdlib/module.rs:290) create separate DynSpace instances.
[IN-MEMORY-ATOMTRIE-INDEX] [NO-BENCHMARK-CLAIMS]
hyperon-space/src/index/:
AtomIndex (mod.rs:159), insert (:177), query (:192), remove (:207)AtomTrie (trie.rs:201, 930 lines), insert (:232), query (:261), remove (:395)Concentrated implementation period 2025-01-31 to 2025-02-11 (initial implementation, GroundingSpace integration, duplication strategy parameter, AtomStorage/AtomTrieNode separation, compactness improvements). Size-prefix optimization landed at 120c2279 (2025-08-26) — "Prefix expressions with size in atomspace index to recognize them faster".
NO quantitative scaling ceilings claimed at this time. Existing benches at hyperon-space/benches/atom_index.rs and lib/benches/grounding_space.rs operate at 100/x10/x100 atom scales only. An empirical bench harness is required for any production scaling claims.
(Phase 4 prior art — re-confirmed at HEAD)
The Hyperon Space write surface is complete at the Space/C/Python layers:
SpaceMut::add / remove / replace at hyperon-space/src/lib.rs:237/255/275GroundingSpace[D] (generic over duplication strategy D) concrete impl at lib/src/space/grounding/mod.rs:14-21; inherent add/remove/replace at :70/:92/:119c/src/space.rs:140-143; observer registration at c/src/space.rs:464python/hyperon/base.py:205-221SpaceObserver / SpaceEvent / SpaceCommon observer pattern at hyperon-space/src/lib.rs:22-126c/src/space.rs:117-119)PATCH-1 (REQUIRED for Phase 4 mirror integration): pybind11 binding for space_register_observer in python/hyperonpy.cpp is missing. Path II (Rust-only bridge service) is the Phase 4 implementation strategy; Path IV (PR upstream) is the upstream-contribution strategy.
[PY-PARTIAL-WITH-GAPS]
Broad coverage:
SpaceRef (base.py:168), add_atom/remove_atom/replace_atom (L205-221)RunnerState (runner.py:24), MeTTa class (L107), run (L206), evaluate atom (L216)hyperonpy.cpp:1017-1026 interpreter steppinghyperonpy.cpp:1047-1053 type checking and lookuphyperonpy.cpp:1070-1122 run context, MeTTa construction, module loadingGap: Python observer registration is NOT bound (PATCH-1 above).
EventAgent (PR #852, merged commit 2fd826d4 2025-03-14) ships at HEAD: python/hyperon/exts/agents/agent_base.py:202-293 defines EventAgent, BasicEventBus at events/basic_bus.py:6. EventAgent uses a generic event bus, NOT bound to SpaceEvent/SpaceObserver — they are disjoint event paths in the same repo.
[C-CORE-ONLY]
Broad runtime surface in c/src/:
space.rs:69 space_new; :140-170 add/remove/replace; :184-237 query/subst/count/iter; :401-419 event accessors; :464 space_register_observer; :632-673 event constructorsmetta.rs:838-882 MeTTa instance construction; :957-969 space/tokenizer accessors; :1005 parser-input run; :1035 atom evaluation; :1062-1094 module loading; :1305-1407 runner-state steppingC headers are auto-generated by cbindgen (per c/cbindgen.toml); there is NO source-controlled c/include/ directory.
python/sandbox/ is a prototype zone, NOT part of the packaged Python module (python/pyproject.toml:38 packages only hyperon).
| Module | Verdict | Notes |
|---|---|---|
sql_space | [SANDBOX-PROTOTYPE] | Postgres custom-Space; 130 lines; naive SQL string concat; not production |
mork | [SANDBOX-PROTOTYPE] | TODOs at L32, L47 |
neurospace | [SANDBOX-PROTOTYPE] | NeuralSpace, IntentSpace |
jetta | [SANDBOX-EXAMPLE-ONLY] | Requires cloning trueagi-io/jetta |
numpy | [SANDBOX-PROTOTYPE] | numme.py experimental |
pytorch | [SANDBOX-PROTOTYPE] | torchme.py Func-Signature JSON for type-aware tensor ops |
bhv_binding | unclassified | Source 1 did not enumerate |
repl | unclassified | Relationship to top-level repl/ Rust crate not characterized |
resolve | unclassified | Source 1 did not enumerate |
S2-S6 must treat these as precedent and adjacency, NOT as packaged interfaces.
[TEST-COVERAGE-ADEQUATE]
Multilayer:
lib/tests/ + inline #[test] blocks (52 in interpreter.rs, 38 in types.rs)c/tests/: check_atom.c, check_runner.c, check_space.c, check_types.cpython/tests/integration_tests/das/Static audit only — tests not run during cluster-pilot extraction.
The Magi project memory reference_hyperon_0210_quirks.md was originally pinned to v0.2.1 (MAGUS pin). Re-verified at HEAD 3f76dc46 (v0.2.10):
[QUIRK-CONFIRMED-AT-HEAD]. BindOp::execute (stdlib/module.rs:269+) registers a token in the tokenizer. NO code path clears or garbage-collects atoms in an already-bound space. Operational guidance: do NOT treat !(bind! &name (new-space)) as a reset of an existing live space. Use explicit (match &name (pattern) (remove-atom &name (pattern))) workaround.[QUIRK-FIXED-SINCE-V0-2-1] (via absence). cond is NOT a builtin operator at HEAD. Use if, case, match, or user-defined equations. The original v0.2.1 quirk "cond is non-reducing" is no longer applicable because cond is not implemented.[QUIRK-CONFIRMED-AT-HEAD]. This is documented nondeterministic semantics, not a defect. Programs requiring deterministic dispatch must use mutually exclusive patterns; e.g., enumerate all symbols explicitly instead of using a generic variable fallback.Source 1 of the MeTTa runtime cluster pilot (closed 2026-05-08). Three-way reviewer reconciliation at:
scripts/archive/metta_runtime_pilot/source1_hyperon_experimental/findings_reconciled_crossmodel.txtPhase 4 prior art locked from AtomSpace Integration Phase 4 cluster pilot (closed 2026-05-05): Source 2 reconciliation at scripts/archive/atomspace_integration_phase4/source2_hyperon_space_writeapi/findings_reconciled_crossmodel.txt.
For PeTTa+metta-morph (S2), MeTTaTron (S3), MeTTaIL+FormalMeTTa (S4), MeTTaLog (S5), jetta+atomspace-metta (S6):
stdlib.metta definitions%Undefined% wildcard baseline3f76dc46